portatour® ISV API (v1.2)

Introduction

portatour® ISV API version:

OpenAPI specification:Download JSON View

Please switch to the latest version to use the latest features.

The ISV API allows companies, so-called partners, to leverage the portatour® Route Planner algorithm in their software. It provides you with the ability to create optimized schedules for field reps. The API is provided as a REST service. The OpenAPI document provided can be used to generate client code for your environment. This documentation guides you through the process of using the ISV API and provides examples of common API calls.

Getting started

To get started, you will need a partner account and an access token.

To obtain a partner account, get in touch with our ISV API contact.
Once you have your partner account, log in to the Partner Portal and create your first access token.
This access token will be used to authenticate your API calls.
Get started with the code snippets in the how-to guides.

Concept

The concept describes the data and how it is used to calculate a schedule for a field rep.

Each field rep is associated with an organization.
An organization contains the field reps of a company within a specific geographic region.
Each field rep has settings, a set of customers, a set of scheduling constraints, and a set of preferred overnight locations.
Based on a field rep's data, a schedule can be calculated.

The following figure shows the hierarchical structure of the data.

Technical Details

A field rep's data is stored by the ISV API in order to
- eliminate the need to repeatedly transfer data that does not change, and to
- perform optimizations in the background that improve the quality of future schedule calculations.
The ISV API considers all time values to be floating times (i.e. the local time of the field rep).
Parallel requests for the same field rep are not permitted.

Editions

The portatour® ISV API is available in the following editions: Basic, Professional and Ultimate. The edition is set for each organization and affects the features and limits available to that organization. Different credits will be charged depending on the edition selected. You can upgrade or downgrade the editions at any time.

See the ISV API Feature List and License Terms for more information on edition features and billing.

Further information

Product homepage: https://www.portatour.com/isv-api
License terms: https://www.portatour.com/isv-api/license-terms/
Support contact: isv-api-contact@portatour.com

Authentication

All requests to the API require an access token to be sent as part of the HTTP headers. Access tokens can be created using the portatour® Partner Portal or the ISV API. The how to use an access token guide will help you get started. Each token is restricted to one of the following scopes:

Partner
Partner level access tokens provide access to all of your organizations and their field reps. Only you should have these tokens. These tokens can only be created manually in the portatour® Partner Portal.
Scenarios of using such tokens in your software:
- Multiple organizations use the same instance of your software.
- Automated creation of access tokens that are scoped to an organization or a field rep.
Organization
Organization level access tokens provide access to a specific organization and its field reps. Only you or the organization for which these tokens were created should have these tokens. The tokens can be created manually in the portatour® Partner Portal or using the ISV API.
Scenario of using such tokens in your software:
- Each organization runs its own instance of your software.
Field Rep
Field rep level access tokens provide access to a specific field rep. Only you, the organization of the field rep, or the field rep for which these tokens were created should have these tokens. These tokens can only be created using the ISV API.
Scenario of using such tokens in your software:
- Each field rep runs your software on a personal device.

Schedule

After creating a field rep, a schedule can be calculated. A field rep's data (e.g. customers) can be uploaded either as part of a schedule calculation call or in advance.

See the list of possible messages that can occur during a schedule calculation. You can also find a list of possible error codes that can also occur during a schedule calculation.

Calculate and retrieve a schedule

POST /1.2/organizations/{organizationId}/fieldReps/{fieldRepId}/schedule/calculate

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.

HTTP timeout recommendations:

For schedules with periods between 1 and 4 weeks, a timeout of 30 seconds is recommended:
- Note: 1-week schedules typically compute in under 5 seconds.
For 16-week schedules, a timeout of 120 seconds is recommended.

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}

Authorizations:AccessToken

Security scheme type: API Key

Header parameter name: pt-access-token

path parameters

organizationId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]
fieldRepId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]

Request body schema: application/json

calculationParameters
CalculationParametersrequired
Specifies the parameters for a schedule calculation.
- fieldRepCurrentLocalDateTime
  string <yyyy-MM-ddTHH:mm> (IsoDateTimeStringMinutesPrecision)required
  The current local time of the field rep. Used to take work and business hours into account when calculating the schedule. The time must be between UTC -13h and UTC +15h.
  
  IsoDateTimeStringMinutesPrecision is a DateTime type that contains values in the format "yyyy-MM-ddTHH:mm", e.g. "2022-01-31T23:59".
- scheduleBeginAt
  string <yyyy-MM-ddTHH:mm> (IsoDateTimeStringMinutesPrecision)required
  The begin time of the schedule. It cannot be more than 24 hours in the past or more than 365 days in the future, relative to the property fieldRepCurrentLocalDateTime.
  
  IsoDateTimeStringMinutesPrecision is a DateTime type that contains values in the format "yyyy-MM-ddTHH:mm", e.g. "2022-01-31T23:59".
- schedulePeriodDays
  integer <int32>required
  Specifies the number of days in the schedule.
  
  Allowed values, depending on the Edition, are
  
  Basic: 1, 2, 3, 4, 5, 6, 7 days
  Professional: additionally 14, 21, 28 days
  Ultimate: additionally 35, 42, 49, 56, 63, 70, 77, 84, 91, 98, 105, 112 days
- customStartLocation
  Location
  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 address and/or geoPosition. If both are specified, the geoPosition is used as the location. If only the address is 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
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
- skipWorkBreakToday
  booleannullable
  Specifies whether to omit the break on the first day of the schedule if the schedule starts with today.
  
  Default: false
- includeRoutePolylinesInSchedule
  booleannullable
  Specifies whether the routePolyline should 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
  stringnullable
  Specifies whether to include only forced calls or calls according to the interval as well. Allowed values are:
  
  "AccordingToCallIntervalsAndForcedCalls"
  "OnlyForcedCalls"
  
  Default: "AccordingToCallIntervalsAndForcedCalls"
- trafficConditionsForFirstRide
  stringnullable
  Specifies whether to use the current traffic or the typical traffic for the first ride of the schedule. Allowed values are:
  
  "TypicalTraffic"
  "CurrentTraffic"
  
  Note: The current traffic can only be taken into account if the first ride starts within the next 15 minutes.
  
  Edition: Ultimate
  
  Default: "TypicalTraffic"
newDataSet
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
  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
  stringrequired[ 1 .. 250 ] characters
  The full name of the field rep.
  
  languageCultureName
  stringrequirednon-empty^[a-z]{2}-[A-Z]{2}$
  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
  HomeLocationrequired
  Specify address and/or geoPosition. If both are specified, the geoPosition is used as the location. If only the address is 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
  HomeAddress
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  stringrequired[ 1 .. 250 ] characters
  Contains the country of the address. This property is required, even if singleLineAddress is set. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
  workingHours
  WorkingHours
  Defines the hours per weekday that a field rep works. At least one day must be set.
  
  monday
  DailyTimeRange
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  tuesday
  DailyTimeRange
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  wednesday
  DailyTimeRange
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  thursday
  DailyTimeRange
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  friday
  DailyTimeRange
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  saturday
  DailyTimeRange
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  sunday
  DailyTimeRange
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  drivingTimeFactors
  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.
  
  Edition: Ultimate
  
  cityRoad
  number <double>[ 0.5 .. 2 ]
  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
  number <double>[ 0.5 .. 2 ]
  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
  number <double>[ 0.5 .. 2 ]
  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
  OvernightStayAwayFromHomeSettings
  Defines the conditions for overnight stays away from home.
  
  Note: If this property is not set, no overnight stays are scheduled.
  
  Edition: Ultimate
  
  isAllowedOnMonday
  booleannullable
  Specifies whether overnight stays away from home are allowed on Mondays.
  
  Default: false
  isAllowedOnTuesday
  booleannullable
  Specifies whether overnight stays away from home are allowed on Tuesdays.
  
  Default: false
  isAllowedOnWednesday
  booleannullable
  Specifies whether overnight stays away from home are allowed on Wednesdays.
  
  Default: false
  isAllowedOnThursday
  booleannullable
  Specifies whether overnight stays away from home are allowed on Thursdays.
  
  Default: false
  isAllowedOnFriday
  booleannullable
  Specifies whether overnight stays away from home are allowed on Fridays
  
  Default: false
  isAllowedOnSaturday
  booleannullable
  Specifies whether overnight stays away from home are allowed on Saturdays.
  
  Default: false
  isAllowedOnSunday
  booleannullable
  Specifies whether overnight stays away from home are allowed on Sundays.
  
  Default: false
  minimumMetersFromHome
  integer <int32>[ 0 .. 999000 ]nullable
  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
  integer <int32>[ 0 .. 999 ]nullable
  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
  integer <int32>[ 0 .. 999 ]nullable
  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
  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
  number <double>[ 0 .. 100 ]
  Specifies the value (in %) of the elapsed call interval after which the next call can be scheduled.
  
  Default: 70
  adherenceToCallingHours
  string
  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
  WorkBreak
  Specifies how to schedule a work break.
  
  Note: If this property is null, no break is scheduled.
  
  scheduleWithin
  TimeRangerequired
  The time range consists of the from time and the to time.
  
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  durationMinutes
  integer <int32>required^[0-9]\d*$
  Specifies the duration of the work break in minutes. The duration must fit within scheduleWithin.
- customers
  array of Customernullable
  Replaces the entire set of customers.
  
  Note: If null, the existing customers of the field rep are kept.
  
  The allowed number of customers, depending on the Edition, are
  
  Basic: 125
  Professional: 500
  Ultimate: 1000
  
  id
  stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
  name
  stringrequired[ 1 .. 250 ] characters
  The name of the customer.
  
  location
  Locationrequired
  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
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
  activatedOn
  string <yyyy-MM-dd> (IsoDateString)required
  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
  string <yyyy-MM-dd> (IsoDateString)nullable
  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's dueAfterLastCallIntervalPercent must be reached. Must not be earlier than activatedOn.
  
  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
  string <yyyy-MM-dd> (IsoDateString)nullable
  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
  CallInterval
  Specifies the interval at which the customer should be called.
  
  Note: If null, the customer has no call interval.
  
  days
  integer <int32>[ 7 .. 730 ]nullable
  The customer's call interval in days. A next call can be scheduled when the dueAfterLastCallIntervalPercent since the last call is reached.
  
  Default: 30
  isAdherencePreferred
  booleannullable
  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
  integer <int32>[ 1 .. 480 ]nullable
  The duration of a call in minutes.
  
  Default: 20
  schedulingRestriction
  stringnullable
  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.
  
  Edition: Ultimate
  
  doForceCall
  booleannullable
  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
  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 isPreferred flag to true for these periods. Preferred periods cause portatour® to schedule the customer preferably within this period.
  
  The field rep's adherenceToCallingHours in generalCustomerSchedulingSettings specifies 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.
  
  Editions: Professional, Ultimate
  
  mondayPeriod1
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
  mondayPeriod2
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
  tuesdayPeriod1
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
  tuesdayPeriod2
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
  wednesdayPeriod1
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
  wednesdayPeriod2
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
  thursdayPeriod1
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
  thursdayPeriod2
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
  fridayPeriod1
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
  fridayPeriod2
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
  saturdayPeriod1
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
  saturdayPeriod2
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
  sundayPeriod1
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
  sundayPeriod2
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
  callBlocks
  array of CallBlocknullable
  Used to block calls from being scheduled for the customer on the specified days, e.g. the customer's holidays.
  
  Editions: Professional, Ultimate
  
  beginOn
  string <yyyy-MM-dd> (IsoDateString)required
  IsoDateString is a date type that contains values in the format "yyyy-MM-dd", e.g. "2022-01-31".
  
  endOn
  string <yyyy-MM-dd> (IsoDateString)required
  IsoDateString is a date type that contains values in the format "yyyy-MM-dd", e.g. "2022-01-31".
  
  description
  string<= 250 charactersnullable
- preferredOvernightLocations
  array of PreferredOvernightLocationnullable
  Replaces the entire set of preferred overnight locations.
  
  Note: If null, the existing preferred overnight locations of the field rep are kept.
  
  Edition: Ultimate
  
  id
  stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
  name
  stringrequired[ 1 .. 250 ] characters
  The name of the preferred overnight location.
  
  location
  Locationrequired
  The location of the preferred overnight location. Specify address and/or geoPosition. If both are specified, the geoPosition is used as the location. If only the address is 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
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
- schedulingConstraints
  array of SchedulingConstraintnullable
  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
  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
  stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
  subject
  stringrequired[ 1 .. 250 ] characters
  locationInformation
  CustomerEventLocationrequired
  Specifies the custom location of the customer event.
  
  locationType
  stringrequirednon-empty
  The allowed values are:
  
  "HomeLocation"
  "CustomerLocation"
  "CustomLocation"
  "Anywhere" (Edition: Ultimate)
  
  If the locationType is "HomeLocation", the home location of the field rep is used. If the locationType is "CustomerLocation", the location of the customer is used. If the locationType is "CustomLocation", the location property is used as the location. If the locationType is "Anywhere", no location is used.
  
  customLocation
  Location
  Required if locationType is "CustomLocation". Must not be set for any other value of locationType. Specifies the custom location of the customer event.
  
  address
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
  startDate
  string <yyyy-MM-dd> (IsoDateString)required
  IsoDateString is a date type that contains values in the format "yyyy-MM-dd", e.g. "2022-01-31".
  
  beginAt
  string <HH:mm> (IsoTimeStringMinutesPrecision)required
  IsoTimeStringMinutesPrecision is a time type that contains values in the format "HH:mm", e.g. "23:59".
  
  endDate
  string <yyyy-MM-dd> (IsoDateString)nullable
  If null, value of startDate is used.
  
  IsoDateString is a date type that contains values in the format "yyyy-MM-dd", e.g. "2022-01-31".
  
  endAt
  string <HH:mm> (IsoTimeStringMinutesPrecision)required
  IsoTimeStringMinutesPrecision is a time type that contains values in the format "HH:mm", e.g. "23:59".
  
  customerId
  stringrequirednon-empty^[a-zA-Z0-9-_{}]+$
  The id of the customer to which this customer event is related.
  
  customerEventWithinTimeFrame
  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.
  
  Editions: Professional, Ultimate
  
  id
  stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
  subject
  stringrequired[ 1 .. 250 ] characters
  locationInformation
  CustomerEventLocationrequired
  Specifies the custom location of the customer event.
  
  locationType
  stringrequirednon-empty
  The allowed values are:
  
  "HomeLocation"
  "CustomerLocation"
  "CustomLocation"
  "Anywhere" (Edition: Ultimate)
  
  If the locationType is "HomeLocation", the home location of the field rep is used. If the locationType is "CustomerLocation", the location of the customer is used. If the locationType is "CustomLocation", the location property is used as the location. If the locationType is "Anywhere", no location is used.
  
  customLocation
  Location
  Required if locationType is "CustomLocation". Must not be set for any other value of locationType. Specifies the custom location of the customer event.
  
  address
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
  date
  string <yyyy-MM-dd> (IsoDateString)required
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)required
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)required
  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
  integer <int32>required^[1-9]\d*$
  The duration of the customer event in minutes.
  
  Note: This value must be less than the difference between earliestBeginAt and latestEndAt.
  
  customerId
  stringrequirednon-empty^[a-zA-Z0-9-_{}]+$
  The id of the customer to which this customer event is related.
  
  customerEventAnytimeOnADay
  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.
  
  Editions: Professional, Ultimate
  
  id
  stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
  subject
  stringrequired[ 1 .. 250 ] characters
  locationInformation
  CustomerEventLocationrequired
  Specifies the custom location of the customer event.
  
  locationType
  stringrequirednon-empty
  The allowed values are:
  
  "HomeLocation"
  "CustomerLocation"
  "CustomLocation"
  "Anywhere" (Edition: Ultimate)
  
  If the locationType is "HomeLocation", the home location of the field rep is used. If the locationType is "CustomerLocation", the location of the customer is used. If the locationType is "CustomLocation", the location property is used as the location. If the locationType is "Anywhere", no location is used.
  
  customLocation
  Location
  Required if locationType is "CustomLocation". Must not be set for any other value of locationType. Specifies the custom location of the customer event.
  
  address
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
  date
  string <yyyy-MM-dd> (IsoDateString)required
  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
  integer <int32>required^[1-9]\d*$
  The duration of the customer event in minutes.
  
  customerId
  stringrequirednon-empty^[a-zA-Z0-9-_{}]+$
  The id of the customer to which this customer event is related.
  
  blocker
  Blocker
  Blocks the scheduling of calls for the field rep during the specified date and time range. It can last for several days.
  
  Editions: Professional, Ultimate
  
  id
  stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
  subject
  stringrequired[ 1 .. 250 ] characters
  locationInformation
  BlockerLocationrequired
  Specifies the location information of the blocker.
  
  locationType
  stringrequirednon-empty
  The allowed types of locations are the following strings:
  
  "HomeLocation"
  "CustomLocation"
  "Anywhere" (Edition: Ultimate)
  
  If the locationType is "CustomLocation", the location property is used as the location. If the locationType is "Anywhere", no location is used.
  
  customLocation
  Location
  Required if locationType is "CustomLocation". Must not be set for any other value of locationType. Specifies the location information of the blocker.
  
  address
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
  startDate
  string <yyyy-MM-dd> (IsoDateString)required
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)nullable
  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
  string <yyyy-MM-dd> (IsoDateString)nullable
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)nullable
  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
  BlockerWithinTimeFrame
  Schedules a blocker for the given duration within the specified date time range.
  
  Editions: Professional, Ultimate
  
  id
  stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
  subject
  stringrequired[ 1 .. 250 ] characters
  locationInformation
  BlockerLocationrequired
  Specifies the location information of the blocker.
  
  locationType
  stringrequirednon-empty
  The allowed types of locations are the following strings:
  
  "HomeLocation"
  "CustomLocation"
  "Anywhere" (Edition: Ultimate)
  
  If the locationType is "CustomLocation", the location property is used as the location. If the locationType is "Anywhere", no location is used.
  
  customLocation
  Location
  Required if locationType is "CustomLocation". Must not be set for any other value of locationType. Specifies the location information of the blocker.
  
  address
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
  date
  string <yyyy-MM-dd> (IsoDateString)required
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)required
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)required
  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
  integer <int32>required^[1-9]\d*$
  The duration of the blocker in minutes.
  
  Note: This value must be less than the difference between earliestBeginAt and latestEndAt.
  
  blockerAnytimeOnADay
  BlockerAnytimeOnADay
  Schedules a blocker for the given duration within the specified day.
  
  Editions: Professional, Ultimate
  
  id
  stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
  subject
  stringrequired[ 1 .. 250 ] characters
  locationInformation
  BlockerLocationrequired
  Specifies the location information of the blocker.
  
  locationType
  stringrequirednon-empty
  The allowed types of locations are the following strings:
  
  "HomeLocation"
  "CustomLocation"
  "Anywhere" (Edition: Ultimate)
  
  If the locationType is "CustomLocation", the location property is used as the location. If the locationType is "Anywhere", no location is used.
  
  customLocation
  Location
  Required if locationType is "CustomLocation". Must not be set for any other value of locationType. Specifies the location information of the blocker.
  
  address
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
  date
  string <yyyy-MM-dd> (IsoDateString)required
  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
  integer <int32>required^[1-9]\d*$
  The duration of the blocker in minutes.
  
  deviatingStartOfDay
  DeviatingStartOfDay
  Starts the workday at a specific location and time.
  
  Editions: Professional, Ultimate
  
  id
  stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
  subject
  stringrequired[ 1 .. 250 ] characters
  locationInformation
  DayBoundaryLocationrequired
  Specifies the location information.
  
  locationType
  stringrequirednon-empty
  The allowed types of locations are the following strings:
  
  "HomeLocation"
  "PreferredOvernightLocation"
  "CustomLocation"
  
  If the locationType is "HomeLocation", the home location of the field rep is used. If the locationType is "PreferredOvernightLocation", the location of the preferred overnight stay is used. If the locationType is "CustomLocation", the location property is used as the location.
  
  customLocation
  Location
  Required if locationType is "CustomLocation". Must not be set for any other value of locationType. Specifies the location information.
  
  address
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
  preferredOvernightLocationId
  stringnullable
  If the locationType is "PreferredOvernightLocation" the preferredOvernightLocationId is required.
  
  date
  string <yyyy-MM-dd> (IsoDateString)required
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)nullable
  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".
  
  deviatingEndOfDay
  DeviatingEndOfDay
  Ends the workday at a specific location and time.
  
  Editions: Professional, Ultimate
  
  id
  stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
  subject
  stringrequired[ 1 .. 250 ] characters
  locationInformation
  DayBoundaryLocationrequired
  Specifies the location information.
  
  locationType
  stringrequirednon-empty
  The allowed types of locations are the following strings:
  
  "HomeLocation"
  "PreferredOvernightLocation"
  "CustomLocation"
  
  If the locationType is "HomeLocation", the home location of the field rep is used. If the locationType is "PreferredOvernightLocation", the location of the preferred overnight stay is used. If the locationType is "CustomLocation", the location property is used as the location.
  
  customLocation
  Location
  Required if locationType is "CustomLocation". Must not be set for any other value of locationType. Specifies the location information.
  
  address
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
  preferredOvernightLocationId
  stringnullable
  If the locationType is "PreferredOvernightLocation" the preferredOvernightLocationId is required.
  
  date
  string <yyyy-MM-dd> (IsoDateString)required
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)nullable
  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".
  
  overnightStay
  OvernightStay
  Schedules an overnight stay at a specific location for a given day.
  
  Editions: Professional, Ultimate
  
  id
  stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
  subject
  stringrequired[ 1 .. 250 ] characters
  locationInformation
  DayBoundaryLocationrequired
  Specifies the location information.
  
  locationType
  stringrequirednon-empty
  The allowed types of locations are the following strings:
  
  "HomeLocation"
  "PreferredOvernightLocation"
  "CustomLocation"
  
  If the locationType is "HomeLocation", the home location of the field rep is used. If the locationType is "PreferredOvernightLocation", the location of the preferred overnight stay is used. If the locationType is "CustomLocation", the location property is used as the location.
  
  customLocation
  Location
  Required if locationType is "CustomLocation". Must not be set for any other value of locationType. Specifies the location information.
  
  address
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
  preferredOvernightLocationId
  stringnullable
  If the locationType is "PreferredOvernightLocation" the preferredOvernightLocationId is required.
  
  startDate
  string <yyyy-MM-dd> (IsoDateString)required
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)nullable
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)nullable
  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".
  
  generic
  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
  stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
  subject
  stringrequired[ 1 .. 250 ] characters
  locationInformation
  GenericLocationrequired
  Specifies the location information of the scheduling constraint.
  
  locationType
  stringrequirednon-empty
  The allowed values are:
  
  "HomeLocation"
  "CustomerLocation"
  "CustomLocation"
  "PreferredOvernightLocation"
  "Anywhere" (Edition: Ultimate)
  
  If the locationType is "CustomLocation", the customLocation property is used as the location. If the locationType is "Anywhere", no location is used.
  
  customLocation
  Location
  Required if locationType is "CustomLocation". Must not be set for any other value of locationType. Specifies the location information of the scheduling constraint.
  
  address
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
  preferredOvernightLocationId
  stringnullable
  If the locationType is "PreferredOvernightLocation" the preferredOvernightLocationId is required.
  
  earliestBeginAt
  string <yyyy-MM-ddTHH:mm> (IsoDateTimeStringMinutesPrecision)required
  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
  string <yyyy-MM-ddTHH:mm> (IsoDateTimeStringMinutesPrecision)nullable
  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
  integer <int32>^[1-9]\d*$nullable
  The duration of the scheduling constraint in minutes.
  
  Note: This value must be less than the difference between earliestBeginAt and latestEndAt.
  
  customerId
  stringnullable
  The id of the customer to which the scheduling constraint is related.

Responses

200 OK

Response schema: application/json

id
string
Unique for each calculated schedule.

days

array of ScheduleDay

The scheduled days.

day
string <yyyy-MM-dd> (IsoDateString)
Date of scheduled day.

IsoDateString is a date type that contains values in the format "yyyy-MM-dd", e.g. "2022-01-31".

rows

array of ScheduleRownullable

One row represents one scheduled item. A typical schedule has multiple rows. For example, a Drive row followed by a StopAtCustomer row and another Drive row.

type
string<= 250 characters
The row type determines which of the subsequent row fields below is set. E.g. if the type is "Drive", only the field drive is set. Possible values are:
- "Stop"
- "Drive"
- "SchedulingConstraintWithoutLocation"
stop
ScheduleStopRow
Specifies a stop. Only set if the row type is "Stop".
- timeFrom
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  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
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  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
  string
  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 type customerEvent.
  "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 type customerEvent.
  "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 type customerEvent.
  "StopAtOtherSchedulingConstraint": A stop due to a scheduling constraint that does not have a customer reference, e.g. a scheduling constraint of type blocker.
  
  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 type overnightstay.
- displayName
  string<= 1000 characters
  Name or subject of the stop.
- location
  Location
  Location of the stop.
  
  address
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
  geocodeWarning
  stringnullable
  This field is used for output-only. Do not set this field.
- customerId
  string<= 40 charactersnullable
  If the stop is associated with a customer, the customer id is provided.
- schedulingConstraintId
  string<= 40 charactersnullable
  If the stop is associated with a scheduling constraint, the scheduling constraint id is provided.
- preferredOvernightLocationId
  string<= 40 charactersnullable
  If the stop is associated with a preferred overnight location, the preferred overnight lcoation id is provided.

drive

ScheduleDriveRow

Specifies a drive. Only set if the row type is "Drive".

timeFrom
string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
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
string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
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
integer <int32>
Drive distance in meters.
routingType
string
The routingType indicates how the routing was made. Possible values are:
- "TypicalTraffic",
- "CurrentTraffic",
- "Beeline"
routePolyline
stringnullable
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 IncludeRoutePolylinesInSchedule is true in the calculationParameters.

interruption

DriveInterruption

An interruption represents a time span during which no driving takes place. It is used to model waiting periods (e.g., waiting for a customer to open) as well as work breaks.

Field reps are not obliged to take interruptions at the suggested times. They are free to choose where and when to pause during their route. However, they should adhere to the duration of the interruption (the interval between interruption.timeFrom and interruption.timeTo) to ensure that arrival at the destination remains on time.

If null, no interruption is scheduled for the drive, which is typically the case.

Example	A	B	C
`drive.timeFrom`	10:00	11:00	12:00
`drive.timeTo`	15:20	11:37	12:10
`drive.interruption.timeFrom`	12:00	11:00	12:00
`drive.interruption.timeTo`	12:45	11:30	12:06
`drive.interruption.containsWorkBreak`	true	true	false
driving duration	4h35min	7min	4min
interruption duration	45min	30min	6min

timeFrom
string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
timeTo
string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
containsWorkBreak
booleanrequired

schedulingConstraintWithoutLocation
SchedulingConstraintWithoutLocationRow
Specifies a period for a scheduling constraint without a location. Only set if the row type is "SchedulingConstraintWithoutLocation".

Note: The timeFrom and timeTo of the schedulingConstraintWithoutLocation overlaps with the timeFrom and timeTo of the previous drive in the schedule. To calculate the driving time of the preceding drive, the duration of the schedulingConstraintWithoutLocation must be added to the interruption duration, which is subtracted from the duration of the time frame during which the drive takes place.

For example, if a schedulingConstraintWithoutLocation with timeFrom of 10:30 and timeTo of 11:00 were to follow the drive from example A in the description of drive.interruption above, the 30-minute duration of the scheduling constraint would be added to the interruption duration, resulting in a total interruption duration of 75 minutes. This would shorten the driving duration to 4 hours and 5 minutes.
- timeFrom
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  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
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  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
  string<= 1000 characters
  Display name of the scheduling constraint.
- schedulingConstraintId
  string
  Id to the scheduling constraint.
- customerId
  stringnullable
  Id of the customer associated with the scheduling constraint.
  
  Note: If null, there is no customer associated with the scheduling constraint.

messages
array of ScheduleMessagenullable
Provide information about the schedule. The possible messages are documented in the schedule messages section.

Note: If null, there are no messages.
- messageId
  string
  Identifies the schedule message.
- severity
  string<= 250 characters
  The severity level of the message. Possible values are:
  
  "Info"
  "Warning"
  "Error"
- text
  string<= 1000 characters
  Is provided in the language of the field rep. Its content is described in the schedule message description.
deviations
Deviations
Deviations of the calculated schedule from the input data used for schedule calculation.

Note: If null, there are no deviations.
- unscheduledSchedulingConstraintsInSchedulePeriod
  array of stringnullable
  List of ids of scheduling constraints that were not scheduled. If not null, the schedule will include messages with id 5048 or id 5050.
  
  Possible reasons:
  
  The scheduling constraint collides with another of your scheduling constraints. Either the scheduling constraints overlap or the time between the scheduling constraints is not sufficient for the required drive from the first to the second scheduling constraint.
  The scheduling constraint is located far away from your starting point or it takes too long to get there, undertake the scheduling constraint and drive back to the home location all within one day.
- unscheduledCustomersWithDoForceCall
  array of stringnullable
  List of ids of customers with doForceCall set that were not scheduled. If not null, the schedule will include a message with id 5049.
  
  Possible reasons:
  
  There are too many customers with doForceCall set and not all of them can be included in the schedule.
  A customer has no or very limited business hours, which are either outside of the field rep's working hours or in conflict with the limited business hours of a different customer with doForceCall or with a scheduling constraint.
  A customer is located far away from your home location so that they cannot be reached within the working hours.
  A customer has no address information or the address could not be geocoded.
- schedulingConstraintsWithDeviatingTime
  array of stringnullable
  List of ids of scheduling constraints that have a deviating time. Scheduling constraints with a deviating time can be either shortened or postponed. If not null, the schedule will include messages with id 5003 or id 5042.
  
  Possible reason for shortening:
  
  To ensure there is enough time to reach a following scheduling constraint on time.
  
  Possible reason for postponement:
  
  To ensure there is enough time to reach the first scheduling constraint of the schedule.

Error responses (10)

400 Bad Request

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

401 Unauthorized

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

402 Payment Required

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

403 Forbidden

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

404 Not Found

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

409 Conflict

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

413 Content Too Large

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

429 Too Many Requests

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

500 Internal ServerError

503 Service Unavailable

Request samples

Payload

Content typeapplication/json

{…}

"calculationParameters": {…}

"fieldRepCurrentLocalDateTime": "2026-09-15T23:57",

"scheduleBeginAt": "2026-09-17T08:00",

"schedulePeriodDays": 7,

"skipWorkBreakToday": false,

"includeRoutePolylinesInSchedule": true,

"customerPlanningMode": "AccordingToCallIntervalsAndForcedCalls",

"trafficConditionsForFirstRide": "TypicalTraffic"

"newDataSet": {…}

"fieldRep": {…}

"name": "Alice",

"languageCultureName": "en-US",

"homeLocation": {…}

"address": {…}

"streetWithHouseNumber": "5366 College Ave",

"postalCode": "94618",

"city": "Oakland",

"state": "CA",

"country": "US"

"geoPosition": {…}

"latitude": 37.839302,

"longitude": -122.25132

}

"workingHours": {…}

"monday": {…}

"from": "08:00:00",

"to": "18:00:00"

"tuesday": {…}

"from": "08:00:00",

"to": "18:00:00"

"wednesday": {…}

"from": "08:00:00",

"to": "18:00:00"

"thursday": {…}

"from": "08:00:00",

"to": "18:00:00"

"friday": {…}

"from": "08:00:00",

"to": "18:00:00"

}

"drivingTimeFactors": {…}

"cityRoad": 1,

"countryRoad": 1,

"highway": 1

"overnightStayAwayFromHomeSettings": {…}

"isAllowedOnMonday": true,

"isAllowedOnTuesday": true,

"isAllowedOnWednesday": true,

"isAllowedOnThursday": true,

"isAllowedOnFriday": false,

"isAllowedOnSaturday": false,

"isAllowedOnSunday": false

"generalCustomerSchedulingSettings": {…}

"dueAfterLastCallIntervalPercent": 70,

"adherenceToCallingHours": "StartOfCall"

"workBreak": {…}

"scheduleWithin": {…}

"from": "12:00:00",

"to": "13:00:00"

"durationMinutes": 30

}

"customers": […]

{…}

"id": "16ff46b54c9047faaa35ecc78e490ae0",

"name": "Williams, Derek",

"location": {…}

"address": {…}

"streetWithHouseNumber": "140 2nd St",

"postalCode": "94971",

"city": "Tomales",

"state": "California",

"country": "USA"

}

"activatedOn": "2025-09-16",

"lastCallOn": "2026-08-19",

"callInterval": {…}

"days": 30,

"isAdherencePreferred": false

"callDurationMinutes": 15,

"doForceCall": false,

"callingHours": {…}

"tuesdayPeriod1": {…}

"from": "07:00:00",

"to": "12:00:00"

"wednesdayPeriod1": {…}

"from": "07:00:00",

"to": "12:00:00"

"thursdayPeriod1": {…}

"from": "07:00:00",

"to": "12:00:00"

}

{…}

"id": "a54bb393d0944271b36ea04172018201",

"name": "Pérez, Kyle",

"location": {…}

"address": {…}

"streetWithHouseNumber": "13431 Green Valley Road",

"postalCode": "95472",

"city": "Sebastopol",

"state": "CA",

"country": "US"

}

"activatedOn": "2025-09-16",

"lastCallOn": "2026-08-19",

"callInterval": {…}

"days": 90,

"isAdherencePreferred": false

"callDurationMinutes": 60,

"doForceCall": false,

"callingHours": {…}

"mondayPeriod1": {…}

"from": "08:00:00",

"to": "18:00:00"

"tuesdayPeriod1": {…}

"from": "08:00:00",

"to": "18:00:00"

"wednesdayPeriod1": {…}

"from": "08:00:00",

"to": "18:00:00"

"thursdayPeriod1": {…}

"from": "08:00:00",

"to": "18:00:00"

"fridayPeriod1": {…}

"from": "08:00:00",

"to": "18:00:00"

}

{…}

"id": "9715f58410274bb88dec83ef8bfa3ce1",

"name": "Stewart, Joel",

"location": {…}

"address": {…}

"streetWithHouseNumber": "10940 River Road",

"postalCode": "95436-9746",

"city": "Forestville",

"state": "CA",

"country": "US"

}

"activatedOn": "2025-09-16",

"lastCallOn": "2026-08-19",

"callInterval": {…}

"days": 90,

"isAdherencePreferred": false

"callDurationMinutes": 30,

"doForceCall": false,

"callingHours": {…}

"mondayPeriod1": {…}

"from": "08:00:00",

"to": "18:00:00"

"tuesdayPeriod1": {…}

"from": "08:00:00",

"to": "18:00:00"

"wednesdayPeriod1": {…}

"from": "08:00:00",

"to": "18:00:00"

"thursdayPeriod1": {…}

"from": "08:00:00",

"to": "18:00:00"

"fridayPeriod1": {…}

"from": "08:00:00",

"to": "18:00:00"

}

"preferredOvernightLocations": […]

{…}

"id": "a3f05a7b968c4e99b01e277672025434",

"name": "Ramada Limited - Santa Clara",

"location": {…}

"address": {…}

"streetWithHouseNumber": "1655 El Camino Real",

"postalCode": "95050",

"city": "Santa Clara",

"state": "CA",

"country": "US"

"geoPosition": {…}

"latitude": 37.35252,

"longitude": -121.95525

}

{…}

"id": "223b848cc7b44a52af0fd991e4eee6ad",

"name": "Best Western Plus Garden Inn - Santa Rosa",

"location": {…}

"address": {…}

"streetWithHouseNumber": "1500 Santa Rosa Avenue",

"postalCode": "95404",

"city": "Santa Rosa",

"state": "CA",

"country": "US"

"geoPosition": {…}

"latitude": 38.42383,

"longitude": -122.71344

}

{…}

"id": "b2d6d1f9c91b4d63b2699fbec5ec9118",

"name": "Hallmark Inn - Davis",

"location": {…}

"address": {…}

"streetWithHouseNumber": "110 F Street ",

"postalCode": "95616",

"city": "Davis ",

"state": "CA",

"country": "US"

"geoPosition": {…}

"latitude": 38.54235,

"longitude": -121.73959

}

"schedulingConstraints": […]

{…}

"customerEventAnytimeOnADay": {…}

"id": "10964307103349fea7ee17b5e99d218d",

"date": "2026-11-11",

"durationMinutes": 60,

"customerId": "16ff46b54c9047faaa35ecc78e490ae0",

"locationInformation": {…}

"locationType": "CustomerLocation"

"subject": "Williams, Derek"

}

{…}

"customerEvent": {…}

"id": "17574c0ae9d9456ab03e57ea4bd10b5a",

"startDate": "2026-11-11",

"beginAt": "08:00",

"endDate": "2026-11-11",

"endAt": "08:30",

"customerId": "a54bb393d0944271b36ea04172018201",

"locationInformation": {…}

"locationType": "CustomLocation",

"customLocation": {…}

"address": {…}

"streetWithHouseNumber": "140 2nd St",

"postalCode": "94971",

"city": "Tomales",

"state": "California",

"country": "USA"

"geoPosition": {…}

"latitude": 38.248,

"longitude": -122.9055

}

"subject": "Pérez, Kyle"

}

]

}

Response samples

200400401402403404409413429

Content typeapplication/json

{…}

"id": "{CB0B35B5-DC10-4F79-88BA-3CB5904EBDDD}",

"days": […]

{…}

"day": "2026-09-17",

"rows": […]

{…}

"type": "Stop",

"stop": {…}

"timeFrom": "08:00:00",

"timeTo": "08:00:00",

"stopType": "DepartureFromHome",

"displayName": "Home location",

"location": {…}

"address": {…}

"streetWithHouseNumber": "5366 College Ave",

"postalCode": "94618",

"city": "Oakland",

"state": "CA",

"country": "US"

"geoPosition": {…}

"latitude": 37.839302,

"longitude": -122.25132

}

{…}

"type": "Drive",

"drive": {…}

"timeFrom": "08:00:00",

"timeTo": "08:38:12",

"distanceMeters": 31122,

"routingType": "TypicalTraffic",

"routePolyline": "sn}eFvediV??mD@wCLKWkGsTMk@Ce@yX}NGOkD_BOk@gAgAm@}@yB_FGg@BaAw@uC_@iA_AmDSoAEeA?m@H_BVuA`@sAn@yA~@gBr@_Bj@yBJy@JwAC{AGgAiAcKIiAKeD@_BN}B`BeLFqAEoCWkD_@aCOk@g@uA{@gBgAuAi@g@qA{@gAg@sFoAaBg@eB_A_A_AsAaAk@Ia@Q[]Yi@W{@_AyE[_FUyBWeB]wAe@sA[u@_@o@w@kAgUgXmCyC{AkAiAo@aBm@iA[uCe@sAI{CISDoBc@y@]sA_A{@}@e@s@o@iA[y@a@kAiD_Qs@aFScCOgHBsJIoCMcBOiAu@kDa@oAaA}Bu@oAia@il@{EgGaF_FeEoDsPiLuJuGqF_DqTkLqAw@sB}A_Ay@uBuBqA{A_BuBoB_D{A{CmAyC}@eCq@_CkBkIa@_Co@kEm@iGYeDW}FKmEC_HDcDN}EPeDl@wH`BcRhEcj@HoA?eDAuAWsEw@iLCcA@oCHcBdBaQb@oDL_BF_BBmBAwAS{Dg@gE}O}cAk@eEmBeSuF{n@sJ_eA_@sFI{BKwEYg\a@}g@FkFN_Et@gI|AoJrCsOz@gFPsC@uAG{AIkAWeBu@oD_@kAk@kAc@u@{@gAi@i@iAy@aBw@iA]uFkAcC_@sDu@eB_A}IaE{C}ABiACe@kB_Km@cBq@w@oC}Ay@}@M]I_@Iw@MsJ@aBf@_GC{AK}@]}As@}BmB}GgEoPw@kD]kBWkCYcFOmBQiAa@_Bg@gAqCyEsTc^u@gAm@s@qViScAeAuAaB_BiCo@sAgDcKsM{a@gDyKe@mBa@wCO_BiBcVMiA_@_CaAwDaFqOsCeJ{AqE[qAcBaL{CeTaBqKi@cCk@iBw@iBi@_A{@gAaAaAuBqAuCyAuBoAqB{AkBeByCcDaB}BeF_I_AeAcA}@iAu@oAi@uAa@yAW}BGgBFuF\}A?wAI}A[_AWaEyA}BgAk@_@uBgBqB{BcA}AmAgCs@qBy@aDa@uCQ_C}Ak^k@mJs@mOCsBD{BNiC~BcSfB}L~E{ZcMaGAF"

}

{…}

"type": "Stop",

"stop": {…}

"timeFrom": "08:38:12",

"timeTo": "09:08:12",

"stopType": "StopAtCustomer",

"displayName": "Clark, Allison",

"location": {…}

"address": {…}

"streetWithHouseNumber": "1101 Alberta Way",

"postalCode": "94521-3799",

"city": "Concord",

"state": "CA",

"country": "US"

"geoPosition": {…}

"latitude": 37.94825,

"longitude": -121.96817

}

"customerId": "aa14d116f577448a9b307ba11f47630b"

}

… 16 more items, use Copy for the full sample

]

{…}

"day": "2026-09-18",

"rows": […]

{…}

"type": "Stop",

"stop": {…}

"timeFrom": "08:00:00",

"timeTo": "08:00:00",

"stopType": "DepartureFromHome",

"displayName": "Home location",

"location": {…}

"address": {…}

"streetWithHouseNumber": "5366 College Ave",

"postalCode": "94618",

"city": "Oakland",

"state": "CA",

"country": "US"

"geoPosition": {…}

"latitude": 37.839302,

"longitude": -122.25132

}

{…}

"type": "Drive",

"drive": {…}

"timeFrom": "08:00:00",

"timeTo": "08:36:54",

"distanceMeters": 38430,

"routingType": "TypicalTraffic",

"routePolyline": "sn}eFvediV??yC@Ab@_AdCsJbVkBnEENIv@EtAJn@tAxE`BzDfB~ItAzD`AtBbAbBrB`CpAdAbB`A|Ap@dAZxAZ`BTxYjD|Aj@`IjAhEt@~Fz@hAXjI~A~@b@x@t@l@`Ap@lBHx@Bz@?f@GhAm@vEIdAwBvPQ`BIjCwEd[c@`EI`D?bAFnAZ|Cd@xCbA~HVrCBzBIvCIbAy@zEmAbF_AtC]x@i@v@q@p@u@j@u@^_AViAJo@BwCA_BKuA@wALaCf@aE~AyPnIyA|@qCv@sAVuWrC}YbEua@bGexA|WcjAdVma@~FqEj@yBCcHXgCOmHmAsAMw@?{AJkLxAsBZ{Bj@{Bt@wB~@sBhA_C`BeHlFQViGlEeMnJqp@|g@_A|@yL`KgSbOuBjB_DbDiBrBwE`GoBtC{A~B{CdFmBtDe@jA_B~E_@bBe@|BWdB]fDY~Ec@j_@_@pW?rJPd\ElBWfFe@nEq@zDk@`C}@vCoAdDy@fBuHrNaCdF{@dCu@hCsAjG_@lCSrBO`CKnDA`w@CvBI~BYbDUnBSvAi@rCeKlf@yA~EiK`Zc@|A]nBKr@OfCAfDBlANlBnA|HHv@JrA@lCAbAE~@g@dFi@xICdPa@xJuCvgAg@`ToCj_Ac@|Qc@lNuA`i@c@`NMtCc@hGq@pGi@nDmA`H{Qd{@kFnW_BvIo@jFuF|j@a@|CSdAo@`C[v@yD~He@bAu@fCUhAMr@SzBGtBTlNIdDOlBKr@o@xCk@~Aq@xAw@nAm@t@_v@|x@yTvUuEfFeAxAw@lAcFnJm@vAqAxEa@dAy@~AmCdEa@t@c@~@Y~@cHxO}Rja@}AhCw@|@{@p@_Af@iAZaAPgBDmAIaJaBgLmB_CU}BOoBEsB@sCPmBVeCd@cBd@mDnAcKrEqBx@gFdCqDpCiDhD{CjCyFpFwPnPcKlG_AZi@@g@Gc@Qe@c@kAyAsGeG}AkByBgDOEe@w@aCqCaHgJV]^d@KN"

}

{…}

"type": "Stop",

"stop": {…}

"timeFrom": "08:36:54",

"timeTo": "09:36:54",

"stopType": "StopAtCustomer",

"displayName": "Allen, Crystal",

"location": {…}

"address": {…}

"streetWithHouseNumber": "160-B North San Pedro Road",

"postalCode": "94903",

"city": "San Rafael",

"state": "CA",

"country": "US"

"geoPosition": {…}

"latitude": 37.99927,

"longitude": -122.52507

}

"customerId": "90833a0467e84552bfcf4453eca2e06e"

}

… 12 more items, use Copy for the full sample

]

{…}

"day": "2026-09-19",

"rows": […]

{…}

"type": "Stop",

"stop": {…}

"timeFrom": "07:30:06",

"timeTo": "07:30:06",

"stopType": "DepartureFromPreferredOvernightLocation",

"displayName": "Overnight stay Best Western Plus Garden Inn - Santa Rosa",

"location": {…}

"address": {…}

"streetWithHouseNumber": "1500 Santa Rosa Avenue",

"postalCode": "95404",

"city": "Santa Rosa",

"state": "CA",

"country": "US"

"geoPosition": {…}

"latitude": 38.42383,

"longitude": -122.71344

}

"preferredOvernightLocationId": "223b848cc7b44a52af0fd991e4eee6ad"

}

{…}

"type": "Drive",

"drive": {…}

"timeFrom": "07:30:06",

"timeTo": "08:00:59",

"distanceMeters": 35783,

"routingType": "TypicalTraffic",

"routePolyline": "}soiF~m~kV?NxA?tAx@`@`@v@|@hCbHj@pANT\^f@V~@P`@CPItCgBXErABlAGjENh`@JfmCTtOFzHC|h@J|OCtAKxBYvBe@tBo@rB{@pBiA~I_GnDoBnBu@dBg@pCg@dBQxAI~C?z@Dv_@vC~CLnUCjXDhGAbw@e@xn@QxANlETjH|@f@R}@hOyCrd@w@|KGTW~CDPs@hMqBvY_AnO}@~J_@xFKlCnI~@tBLpB@dAExAOjB[pBi@pAg@jY{Mh@SNBnA_@pBY~CQjJ[nEEHGxBBxTz@jK\nJJ`BYbA_@r@g@bAgApFfC`RlHnBb@nb@nIp@XdAj@lAfAzF|Fv@p@|ClBnA~@b@b@t@~@bEtEnA`A`Bp@x]nJpWlHJtBNhBRtArCbMhAxDHh@rBxHvC`P|AzGhD|Mn@fBtApC`BdCrD`EjJxJhAhA`At@nh@rT`@VrFvEfAv@d@Vj@RrVdGn@FlAAvEa@jVgCrAK~B?@`HNfRIxG?tECHAnCKrBKv@i@tCYr@dAnAZr@Nh@P~Q?|GJ`HHlP?|b@N|MD|G\|KPlEn@|LdBpYl@fO|Dfp@zCdcANlChAjN~Ct^LfD@pAKhOUvPZpN?xAcChSYnA{@~BUx@yEtWMrBB`BDf@ZtAVp@`@j@rMzK|@~@jAr@x@RjBV~@VtEjCfAx@\Zr@`An@fAf@nAXhAx@~E^hAnF~Kr@pBVhARlAv@hHfDvRf@lDdE`d@rHbt@h@bFDx@@vAWdo@E`UHhBf@xD@bA_Le@yHKgNi@GfDX@"

}

{…}

"type": "Stop",

"stop": {…}

"timeFrom": "08:00:59",

"timeTo": "08:30:00",

"stopType": "StopAtCustomerSchedulingConstraint",

"displayName": "Pérez, Kyle",

"location": {…}

"address": {…}

"streetWithHouseNumber": "140 2nd St",

"postalCode": "94971",

"city": "Tomales",

"state": "California",

"country": "USA"

"geoPosition": {…}

"latitude": 38.46104,

"longitude": -122.93607

}

"customerId": "a54bb393d0944271b36ea04172018201",

"schedulingConstraintId": "17574c0ae9d9456ab03e57ea4bd10b5a"

}

… 14 more items, use Copy for the full sample

]

… 2 more items, use Copy for the full sample

"messages": []

}

Content typeapplication/json

{…}

"statusCode": 400,

"message": "Invalid arguments",

"errorCode": "1011",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 401,

"message": "Access token not valid",

"errorCode": "1300",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 402,

"message": "License expired. Please contact isv-api-contact@portatour.com.",

"errorCode": "1159",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 403,

"message": "The provided access token cannot be used for the given operation or in the given context.",

"errorCode": "1304",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 404,

"message": "Resource not found",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 409,

"message": "Calculation of a schedule is currently running.",

"errorCode": "1213",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 413,

"message": "Content too large",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 429,

"message": "Too many requests",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Async calculate a schedule

POST /1.2/organizations/{organizationId}/fieldReps/{fieldRepId}/schedule/startCalculation

Starts a calculation of a schedule based on the calculation parameters and the field rep's data. 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. The current status of the calculation can be polled using retrieve async schedule calculation result and the returned calculationId. Alternatively use the URL returned in the "location" HTTP response header.

Only one schedule calculation can run at a time. If a new schedule calculation (synchronous or asynchronous) is started while an asynchronous schedule is being calculated, the ongoing calculation is aborted.

Note: Starting a new schedule calculation also discards any previous results.

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}

Authorizations:AccessToken

Security scheme type: API Key

Header parameter name: pt-access-token

path parameters

organizationId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]
fieldRepId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]

Request body schema: application/json

calculationParameters
CalculationParametersrequired
Specifies the parameters for a schedule calculation.
- fieldRepCurrentLocalDateTime
  string <yyyy-MM-ddTHH:mm> (IsoDateTimeStringMinutesPrecision)required
  The current local time of the field rep. Used to take work and business hours into account when calculating the schedule. The time must be between UTC -13h and UTC +15h.
  
  IsoDateTimeStringMinutesPrecision is a DateTime type that contains values in the format "yyyy-MM-ddTHH:mm", e.g. "2022-01-31T23:59".
- scheduleBeginAt
  string <yyyy-MM-ddTHH:mm> (IsoDateTimeStringMinutesPrecision)required
  The begin time of the schedule. It cannot be more than 24 hours in the past or more than 365 days in the future, relative to the property fieldRepCurrentLocalDateTime.
  
  IsoDateTimeStringMinutesPrecision is a DateTime type that contains values in the format "yyyy-MM-ddTHH:mm", e.g. "2022-01-31T23:59".
- schedulePeriodDays
  integer <int32>required
  Specifies the number of days in the schedule.
  
  Allowed values, depending on the Edition, are
  
  Basic: 1, 2, 3, 4, 5, 6, 7 days
  Professional: additionally 14, 21, 28 days
  Ultimate: additionally 35, 42, 49, 56, 63, 70, 77, 84, 91, 98, 105, 112 days
- customStartLocation
  Location
  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 address and/or geoPosition. If both are specified, the geoPosition is used as the location. If only the address is 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
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
- skipWorkBreakToday
  booleannullable
  Specifies whether to omit the break on the first day of the schedule if the schedule starts with today.
  
  Default: false
- includeRoutePolylinesInSchedule
  booleannullable
  Specifies whether the routePolyline should 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
  stringnullable
  Specifies whether to include only forced calls or calls according to the interval as well. Allowed values are:
  
  "AccordingToCallIntervalsAndForcedCalls"
  "OnlyForcedCalls"
  
  Default: "AccordingToCallIntervalsAndForcedCalls"
- trafficConditionsForFirstRide
  stringnullable
  Specifies whether to use the current traffic or the typical traffic for the first ride of the schedule. Allowed values are:
  
  "TypicalTraffic"
  "CurrentTraffic"
  
  Note: The current traffic can only be taken into account if the first ride starts within the next 15 minutes.
  
  Edition: Ultimate
  
  Default: "TypicalTraffic"
newDataSet
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
  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
  stringrequired[ 1 .. 250 ] characters
  The full name of the field rep.
  
  languageCultureName
  stringrequirednon-empty^[a-z]{2}-[A-Z]{2}$
  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
  HomeLocationrequired
  Specify address and/or geoPosition. If both are specified, the geoPosition is used as the location. If only the address is 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
  HomeAddress
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  stringrequired[ 1 .. 250 ] characters
  Contains the country of the address. This property is required, even if singleLineAddress is set. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
  workingHours
  WorkingHours
  Defines the hours per weekday that a field rep works. At least one day must be set.
  
  monday
  DailyTimeRange
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  tuesday
  DailyTimeRange
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  wednesday
  DailyTimeRange
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  thursday
  DailyTimeRange
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  friday
  DailyTimeRange
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  saturday
  DailyTimeRange
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  sunday
  DailyTimeRange
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  drivingTimeFactors
  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.
  
  Edition: Ultimate
  
  cityRoad
  number <double>[ 0.5 .. 2 ]
  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
  number <double>[ 0.5 .. 2 ]
  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
  number <double>[ 0.5 .. 2 ]
  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
  OvernightStayAwayFromHomeSettings
  Defines the conditions for overnight stays away from home.
  
  Note: If this property is not set, no overnight stays are scheduled.
  
  Edition: Ultimate
  
  isAllowedOnMonday
  booleannullable
  Specifies whether overnight stays away from home are allowed on Mondays.
  
  Default: false
  isAllowedOnTuesday
  booleannullable
  Specifies whether overnight stays away from home are allowed on Tuesdays.
  
  Default: false
  isAllowedOnWednesday
  booleannullable
  Specifies whether overnight stays away from home are allowed on Wednesdays.
  
  Default: false
  isAllowedOnThursday
  booleannullable
  Specifies whether overnight stays away from home are allowed on Thursdays.
  
  Default: false
  isAllowedOnFriday
  booleannullable
  Specifies whether overnight stays away from home are allowed on Fridays
  
  Default: false
  isAllowedOnSaturday
  booleannullable
  Specifies whether overnight stays away from home are allowed on Saturdays.
  
  Default: false
  isAllowedOnSunday
  booleannullable
  Specifies whether overnight stays away from home are allowed on Sundays.
  
  Default: false
  minimumMetersFromHome
  integer <int32>[ 0 .. 999000 ]nullable
  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
  integer <int32>[ 0 .. 999 ]nullable
  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
  integer <int32>[ 0 .. 999 ]nullable
  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
  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
  number <double>[ 0 .. 100 ]
  Specifies the value (in %) of the elapsed call interval after which the next call can be scheduled.
  
  Default: 70
  adherenceToCallingHours
  string
  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
  WorkBreak
  Specifies how to schedule a work break.
  
  Note: If this property is null, no break is scheduled.
  
  scheduleWithin
  TimeRangerequired
  The time range consists of the from time and the to time.
  
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  durationMinutes
  integer <int32>required^[0-9]\d*$
  Specifies the duration of the work break in minutes. The duration must fit within scheduleWithin.
- customers
  array of Customernullable
  Replaces the entire set of customers.
  
  Note: If null, the existing customers of the field rep are kept.
  
  The allowed number of customers, depending on the Edition, are
  
  Basic: 125
  Professional: 500
  Ultimate: 1000
  
  id
  stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
  name
  stringrequired[ 1 .. 250 ] characters
  The name of the customer.
  
  location
  Locationrequired
  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
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
  activatedOn
  string <yyyy-MM-dd> (IsoDateString)required
  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
  string <yyyy-MM-dd> (IsoDateString)nullable
  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's dueAfterLastCallIntervalPercent must be reached. Must not be earlier than activatedOn.
  
  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
  string <yyyy-MM-dd> (IsoDateString)nullable
  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
  CallInterval
  Specifies the interval at which the customer should be called.
  
  Note: If null, the customer has no call interval.
  
  days
  integer <int32>[ 7 .. 730 ]nullable
  The customer's call interval in days. A next call can be scheduled when the dueAfterLastCallIntervalPercent since the last call is reached.
  
  Default: 30
  isAdherencePreferred
  booleannullable
  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
  integer <int32>[ 1 .. 480 ]nullable
  The duration of a call in minutes.
  
  Default: 20
  schedulingRestriction
  stringnullable
  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.
  
  Edition: Ultimate
  
  doForceCall
  booleannullable
  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
  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 isPreferred flag to true for these periods. Preferred periods cause portatour® to schedule the customer preferably within this period.
  
  The field rep's adherenceToCallingHours in generalCustomerSchedulingSettings specifies 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.
  
  Editions: Professional, Ultimate
  
  mondayPeriod1
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
  mondayPeriod2
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
  tuesdayPeriod1
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
  tuesdayPeriod2
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
  wednesdayPeriod1
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
  wednesdayPeriod2
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
  thursdayPeriod1
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
  thursdayPeriod2
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
  fridayPeriod1
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
  fridayPeriod2
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
  saturdayPeriod1
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
  saturdayPeriod2
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
  sundayPeriod1
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
  sundayPeriod2
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
  callBlocks
  array of CallBlocknullable
  Used to block calls from being scheduled for the customer on the specified days, e.g. the customer's holidays.
  
  Editions: Professional, Ultimate
  
  beginOn
  string <yyyy-MM-dd> (IsoDateString)required
  IsoDateString is a date type that contains values in the format "yyyy-MM-dd", e.g. "2022-01-31".
  
  endOn
  string <yyyy-MM-dd> (IsoDateString)required
  IsoDateString is a date type that contains values in the format "yyyy-MM-dd", e.g. "2022-01-31".
  
  description
  string<= 250 charactersnullable
- preferredOvernightLocations
  array of PreferredOvernightLocationnullable
  Replaces the entire set of preferred overnight locations.
  
  Note: If null, the existing preferred overnight locations of the field rep are kept.
  
  Edition: Ultimate
  
  id
  stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
  name
  stringrequired[ 1 .. 250 ] characters
  The name of the preferred overnight location.
  
  location
  Locationrequired
  The location of the preferred overnight location. Specify address and/or geoPosition. If both are specified, the geoPosition is used as the location. If only the address is 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
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
- schedulingConstraints
  array of SchedulingConstraintnullable
  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
  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
  stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
  subject
  stringrequired[ 1 .. 250 ] characters
  locationInformation
  CustomerEventLocationrequired
  Specifies the custom location of the customer event.
  
  locationType
  stringrequirednon-empty
  The allowed values are:
  
  "HomeLocation"
  "CustomerLocation"
  "CustomLocation"
  "Anywhere" (Edition: Ultimate)
  
  If the locationType is "HomeLocation", the home location of the field rep is used. If the locationType is "CustomerLocation", the location of the customer is used. If the locationType is "CustomLocation", the location property is used as the location. If the locationType is "Anywhere", no location is used.
  
  customLocation
  Location
  Required if locationType is "CustomLocation". Must not be set for any other value of locationType. Specifies the custom location of the customer event.
  
  address
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
  startDate
  string <yyyy-MM-dd> (IsoDateString)required
  IsoDateString is a date type that contains values in the format "yyyy-MM-dd", e.g. "2022-01-31".
  
  beginAt
  string <HH:mm> (IsoTimeStringMinutesPrecision)required
  IsoTimeStringMinutesPrecision is a time type that contains values in the format "HH:mm", e.g. "23:59".
  
  endDate
  string <yyyy-MM-dd> (IsoDateString)nullable
  If null, value of startDate is used.
  
  IsoDateString is a date type that contains values in the format "yyyy-MM-dd", e.g. "2022-01-31".
  
  endAt
  string <HH:mm> (IsoTimeStringMinutesPrecision)required
  IsoTimeStringMinutesPrecision is a time type that contains values in the format "HH:mm", e.g. "23:59".
  
  customerId
  stringrequirednon-empty^[a-zA-Z0-9-_{}]+$
  The id of the customer to which this customer event is related.
  
  customerEventWithinTimeFrame
  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.
  
  Editions: Professional, Ultimate
  
  id
  stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
  subject
  stringrequired[ 1 .. 250 ] characters
  locationInformation
  CustomerEventLocationrequired
  Specifies the custom location of the customer event.
  
  locationType
  stringrequirednon-empty
  The allowed values are:
  
  "HomeLocation"
  "CustomerLocation"
  "CustomLocation"
  "Anywhere" (Edition: Ultimate)
  
  If the locationType is "HomeLocation", the home location of the field rep is used. If the locationType is "CustomerLocation", the location of the customer is used. If the locationType is "CustomLocation", the location property is used as the location. If the locationType is "Anywhere", no location is used.
  
  customLocation
  Location
  Required if locationType is "CustomLocation". Must not be set for any other value of locationType. Specifies the custom location of the customer event.
  
  address
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
  date
  string <yyyy-MM-dd> (IsoDateString)required
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)required
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)required
  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
  integer <int32>required^[1-9]\d*$
  The duration of the customer event in minutes.
  
  Note: This value must be less than the difference between earliestBeginAt and latestEndAt.
  
  customerId
  stringrequirednon-empty^[a-zA-Z0-9-_{}]+$
  The id of the customer to which this customer event is related.
  
  customerEventAnytimeOnADay
  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.
  
  Editions: Professional, Ultimate
  
  id
  stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
  subject
  stringrequired[ 1 .. 250 ] characters
  locationInformation
  CustomerEventLocationrequired
  Specifies the custom location of the customer event.
  
  locationType
  stringrequirednon-empty
  The allowed values are:
  
  "HomeLocation"
  "CustomerLocation"
  "CustomLocation"
  "Anywhere" (Edition: Ultimate)
  
  If the locationType is "HomeLocation", the home location of the field rep is used. If the locationType is "CustomerLocation", the location of the customer is used. If the locationType is "CustomLocation", the location property is used as the location. If the locationType is "Anywhere", no location is used.
  
  customLocation
  Location
  Required if locationType is "CustomLocation". Must not be set for any other value of locationType. Specifies the custom location of the customer event.
  
  address
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
  date
  string <yyyy-MM-dd> (IsoDateString)required
  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
  integer <int32>required^[1-9]\d*$
  The duration of the customer event in minutes.
  
  customerId
  stringrequirednon-empty^[a-zA-Z0-9-_{}]+$
  The id of the customer to which this customer event is related.
  
  blocker
  Blocker
  Blocks the scheduling of calls for the field rep during the specified date and time range. It can last for several days.
  
  Editions: Professional, Ultimate
  
  id
  stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
  subject
  stringrequired[ 1 .. 250 ] characters
  locationInformation
  BlockerLocationrequired
  Specifies the location information of the blocker.
  
  locationType
  stringrequirednon-empty
  The allowed types of locations are the following strings:
  
  "HomeLocation"
  "CustomLocation"
  "Anywhere" (Edition: Ultimate)
  
  If the locationType is "CustomLocation", the location property is used as the location. If the locationType is "Anywhere", no location is used.
  
  customLocation
  Location
  Required if locationType is "CustomLocation". Must not be set for any other value of locationType. Specifies the location information of the blocker.
  
  address
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
  startDate
  string <yyyy-MM-dd> (IsoDateString)required
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)nullable
  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
  string <yyyy-MM-dd> (IsoDateString)nullable
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)nullable
  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
  BlockerWithinTimeFrame
  Schedules a blocker for the given duration within the specified date time range.
  
  Editions: Professional, Ultimate
  
  id
  stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
  subject
  stringrequired[ 1 .. 250 ] characters
  locationInformation
  BlockerLocationrequired
  Specifies the location information of the blocker.
  
  locationType
  stringrequirednon-empty
  The allowed types of locations are the following strings:
  
  "HomeLocation"
  "CustomLocation"
  "Anywhere" (Edition: Ultimate)
  
  If the locationType is "CustomLocation", the location property is used as the location. If the locationType is "Anywhere", no location is used.
  
  customLocation
  Location
  Required if locationType is "CustomLocation". Must not be set for any other value of locationType. Specifies the location information of the blocker.
  
  address
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
  date
  string <yyyy-MM-dd> (IsoDateString)required
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)required
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)required
  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
  integer <int32>required^[1-9]\d*$
  The duration of the blocker in minutes.
  
  Note: This value must be less than the difference between earliestBeginAt and latestEndAt.
  
  blockerAnytimeOnADay
  BlockerAnytimeOnADay
  Schedules a blocker for the given duration within the specified day.
  
  Editions: Professional, Ultimate
  
  id
  stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
  subject
  stringrequired[ 1 .. 250 ] characters
  locationInformation
  BlockerLocationrequired
  Specifies the location information of the blocker.
  
  locationType
  stringrequirednon-empty
  The allowed types of locations are the following strings:
  
  "HomeLocation"
  "CustomLocation"
  "Anywhere" (Edition: Ultimate)
  
  If the locationType is "CustomLocation", the location property is used as the location. If the locationType is "Anywhere", no location is used.
  
  customLocation
  Location
  Required if locationType is "CustomLocation". Must not be set for any other value of locationType. Specifies the location information of the blocker.
  
  address
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
  date
  string <yyyy-MM-dd> (IsoDateString)required
  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
  integer <int32>required^[1-9]\d*$
  The duration of the blocker in minutes.
  
  deviatingStartOfDay
  DeviatingStartOfDay
  Starts the workday at a specific location and time.
  
  Editions: Professional, Ultimate
  
  id
  stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
  subject
  stringrequired[ 1 .. 250 ] characters
  locationInformation
  DayBoundaryLocationrequired
  Specifies the location information.
  
  locationType
  stringrequirednon-empty
  The allowed types of locations are the following strings:
  
  "HomeLocation"
  "PreferredOvernightLocation"
  "CustomLocation"
  
  If the locationType is "HomeLocation", the home location of the field rep is used. If the locationType is "PreferredOvernightLocation", the location of the preferred overnight stay is used. If the locationType is "CustomLocation", the location property is used as the location.
  
  customLocation
  Location
  Required if locationType is "CustomLocation". Must not be set for any other value of locationType. Specifies the location information.
  
  address
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
  preferredOvernightLocationId
  stringnullable
  If the locationType is "PreferredOvernightLocation" the preferredOvernightLocationId is required.
  
  date
  string <yyyy-MM-dd> (IsoDateString)required
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)nullable
  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".
  
  deviatingEndOfDay
  DeviatingEndOfDay
  Ends the workday at a specific location and time.
  
  Editions: Professional, Ultimate
  
  id
  stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
  subject
  stringrequired[ 1 .. 250 ] characters
  locationInformation
  DayBoundaryLocationrequired
  Specifies the location information.
  
  locationType
  stringrequirednon-empty
  The allowed types of locations are the following strings:
  
  "HomeLocation"
  "PreferredOvernightLocation"
  "CustomLocation"
  
  If the locationType is "HomeLocation", the home location of the field rep is used. If the locationType is "PreferredOvernightLocation", the location of the preferred overnight stay is used. If the locationType is "CustomLocation", the location property is used as the location.
  
  customLocation
  Location
  Required if locationType is "CustomLocation". Must not be set for any other value of locationType. Specifies the location information.
  
  address
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
  preferredOvernightLocationId
  stringnullable
  If the locationType is "PreferredOvernightLocation" the preferredOvernightLocationId is required.
  
  date
  string <yyyy-MM-dd> (IsoDateString)required
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)nullable
  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".
  
  overnightStay
  OvernightStay
  Schedules an overnight stay at a specific location for a given day.
  
  Editions: Professional, Ultimate
  
  id
  stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
  subject
  stringrequired[ 1 .. 250 ] characters
  locationInformation
  DayBoundaryLocationrequired
  Specifies the location information.
  
  locationType
  stringrequirednon-empty
  The allowed types of locations are the following strings:
  
  "HomeLocation"
  "PreferredOvernightLocation"
  "CustomLocation"
  
  If the locationType is "HomeLocation", the home location of the field rep is used. If the locationType is "PreferredOvernightLocation", the location of the preferred overnight stay is used. If the locationType is "CustomLocation", the location property is used as the location.
  
  customLocation
  Location
  Required if locationType is "CustomLocation". Must not be set for any other value of locationType. Specifies the location information.
  
  address
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
  preferredOvernightLocationId
  stringnullable
  If the locationType is "PreferredOvernightLocation" the preferredOvernightLocationId is required.
  
  startDate
  string <yyyy-MM-dd> (IsoDateString)required
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)nullable
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)nullable
  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".
  
  generic
  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
  stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
  subject
  stringrequired[ 1 .. 250 ] characters
  locationInformation
  GenericLocationrequired
  Specifies the location information of the scheduling constraint.
  
  locationType
  stringrequirednon-empty
  The allowed values are:
  
  "HomeLocation"
  "CustomerLocation"
  "CustomLocation"
  "PreferredOvernightLocation"
  "Anywhere" (Edition: Ultimate)
  
  If the locationType is "CustomLocation", the customLocation property is used as the location. If the locationType is "Anywhere", no location is used.
  
  customLocation
  Location
  Required if locationType is "CustomLocation". Must not be set for any other value of locationType. Specifies the location information of the scheduling constraint.
  
  address
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
  preferredOvernightLocationId
  stringnullable
  If the locationType is "PreferredOvernightLocation" the preferredOvernightLocationId is required.
  
  earliestBeginAt
  string <yyyy-MM-ddTHH:mm> (IsoDateTimeStringMinutesPrecision)required
  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
  string <yyyy-MM-ddTHH:mm> (IsoDateTimeStringMinutesPrecision)nullable
  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
  integer <int32>^[1-9]\d*$nullable
  The duration of the scheduling constraint in minutes.
  
  Note: This value must be less than the difference between earliestBeginAt and latestEndAt.
  
  customerId
  stringnullable
  The id of the customer to which the scheduling constraint is related.

Responses

202 Accepted

Response schema: application/json

calculationId
string
Is used to retrieve the schedule calculation result.

Error responses (10)

400 Bad Request

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

401 Unauthorized

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

402 Payment Required

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

403 Forbidden

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

404 Not Found

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

409 Conflict

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

413 Content Too Large

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

429 Too Many Requests

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

500 Internal ServerError

503 Service Unavailable

Request samples

Payload

Content typeapplication/json

{…}

"calculationParameters": {…}

"fieldRepCurrentLocalDateTime": "2026-09-15T23:57",

"scheduleBeginAt": "2026-09-17T08:00",

"schedulePeriodDays": 7,

"skipWorkBreakToday": false,

"includeRoutePolylinesInSchedule": true,

"customerPlanningMode": "AccordingToCallIntervalsAndForcedCalls",

"trafficConditionsForFirstRide": "TypicalTraffic"

"newDataSet": {…}

"fieldRep": {…}

"name": "Alice",

"languageCultureName": "en-US",

"homeLocation": {…}

"address": {…}

"streetWithHouseNumber": "5366 College Ave",

"postalCode": "94618",

"city": "Oakland",

"state": "CA",

"country": "US"

"geoPosition": {…}

"latitude": 37.839302,

"longitude": -122.25132

}

"workingHours": {…}

"monday": {…}

"from": "08:00:00",

"to": "18:00:00"

"tuesday": {…}

"from": "08:00:00",

"to": "18:00:00"

"wednesday": {…}

"from": "08:00:00",

"to": "18:00:00"

"thursday": {…}

"from": "08:00:00",

"to": "18:00:00"

"friday": {…}

"from": "08:00:00",

"to": "18:00:00"

}

"drivingTimeFactors": {…}

"cityRoad": 1,

"countryRoad": 1,

"highway": 1

"overnightStayAwayFromHomeSettings": {…}

"isAllowedOnMonday": true,

"isAllowedOnTuesday": true,

"isAllowedOnWednesday": true,

"isAllowedOnThursday": true,

"isAllowedOnFriday": false,

"isAllowedOnSaturday": false,

"isAllowedOnSunday": false

"generalCustomerSchedulingSettings": {…}

"dueAfterLastCallIntervalPercent": 70,

"adherenceToCallingHours": "StartOfCall"

"workBreak": {…}

"scheduleWithin": {…}

"from": "12:00:00",

"to": "13:00:00"

"durationMinutes": 30

}

"customers": […]

{…}

"id": "16ff46b54c9047faaa35ecc78e490ae0",

"name": "Williams, Derek",

"location": {…}

"address": {…}

"streetWithHouseNumber": "140 2nd St",

"postalCode": "94971",

"city": "Tomales",

"state": "California",

"country": "USA"

}

"activatedOn": "2025-09-16",

"lastCallOn": "2026-08-19",

"callInterval": {…}

"days": 30,

"isAdherencePreferred": false

"callDurationMinutes": 15,

"doForceCall": false,

"callingHours": {…}

"tuesdayPeriod1": {…}

"from": "07:00:00",

"to": "12:00:00"

"wednesdayPeriod1": {…}

"from": "07:00:00",

"to": "12:00:00"

"thursdayPeriod1": {…}

"from": "07:00:00",

"to": "12:00:00"

}

{…}

"id": "a54bb393d0944271b36ea04172018201",

"name": "Pérez, Kyle",

"location": {…}

"address": {…}

"streetWithHouseNumber": "13431 Green Valley Road",

"postalCode": "95472",

"city": "Sebastopol",

"state": "CA",

"country": "US"

}

"activatedOn": "2025-09-16",

"lastCallOn": "2026-08-19",

"callInterval": {…}

"days": 90,

"isAdherencePreferred": false

"callDurationMinutes": 60,

"doForceCall": false,

"callingHours": {…}

"mondayPeriod1": {…}

"from": "08:00:00",

"to": "18:00:00"

"tuesdayPeriod1": {…}

"from": "08:00:00",

"to": "18:00:00"

"wednesdayPeriod1": {…}

"from": "08:00:00",

"to": "18:00:00"

"thursdayPeriod1": {…}

"from": "08:00:00",

"to": "18:00:00"

"fridayPeriod1": {…}

"from": "08:00:00",

"to": "18:00:00"

}

{…}

"id": "9715f58410274bb88dec83ef8bfa3ce1",

"name": "Stewart, Joel",

"location": {…}

"address": {…}

"streetWithHouseNumber": "10940 River Road",

"postalCode": "95436-9746",

"city": "Forestville",

"state": "CA",

"country": "US"

}

"activatedOn": "2025-09-16",

"lastCallOn": "2026-08-19",

"callInterval": {…}

"days": 90,

"isAdherencePreferred": false

"callDurationMinutes": 30,

"doForceCall": false,

"callingHours": {…}

"mondayPeriod1": {…}

"from": "08:00:00",

"to": "18:00:00"

"tuesdayPeriod1": {…}

"from": "08:00:00",

"to": "18:00:00"

"wednesdayPeriod1": {…}

"from": "08:00:00",

"to": "18:00:00"

"thursdayPeriod1": {…}

"from": "08:00:00",

"to": "18:00:00"

"fridayPeriod1": {…}

"from": "08:00:00",

"to": "18:00:00"

}

"preferredOvernightLocations": […]

{…}

"id": "a3f05a7b968c4e99b01e277672025434",

"name": "Ramada Limited - Santa Clara",

"location": {…}

"address": {…}

"streetWithHouseNumber": "1655 El Camino Real",

"postalCode": "95050",

"city": "Santa Clara",

"state": "CA",

"country": "US"

"geoPosition": {…}

"latitude": 37.35252,

"longitude": -121.95525

}

{…}

"id": "223b848cc7b44a52af0fd991e4eee6ad",

"name": "Best Western Plus Garden Inn - Santa Rosa",

"location": {…}

"address": {…}

"streetWithHouseNumber": "1500 Santa Rosa Avenue",

"postalCode": "95404",

"city": "Santa Rosa",

"state": "CA",

"country": "US"

"geoPosition": {…}

"latitude": 38.42383,

"longitude": -122.71344

}

{…}

"id": "b2d6d1f9c91b4d63b2699fbec5ec9118",

"name": "Hallmark Inn - Davis",

"location": {…}

"address": {…}

"streetWithHouseNumber": "110 F Street ",

"postalCode": "95616",

"city": "Davis ",

"state": "CA",

"country": "US"

"geoPosition": {…}

"latitude": 38.54235,

"longitude": -121.73959

}

"schedulingConstraints": […]

{…}

"customerEventAnytimeOnADay": {…}

"id": "10964307103349fea7ee17b5e99d218d",

"date": "2026-11-11",

"durationMinutes": 60,

"customerId": "16ff46b54c9047faaa35ecc78e490ae0",

"locationInformation": {…}

"locationType": "CustomerLocation"

"subject": "Williams, Derek"

}

{…}

"customerEvent": {…}

"id": "17574c0ae9d9456ab03e57ea4bd10b5a",

"startDate": "2026-11-11",

"beginAt": "08:00",

"endDate": "2026-11-11",

"endAt": "08:30",

"customerId": "a54bb393d0944271b36ea04172018201",

"locationInformation": {…}

"locationType": "CustomLocation",

"customLocation": {…}

"address": {…}

"streetWithHouseNumber": "140 2nd St",

"postalCode": "94971",

"city": "Tomales",

"state": "California",

"country": "USA"

"geoPosition": {…}

"latitude": 38.248,

"longitude": -122.9055

}

"subject": "Pérez, Kyle"

}

]

}

Response samples

202400401402403404409413429

Content typeapplication/json

{…}

"CalculationId": "{5E548684-792B-487A-B382-3405518D014F}"

}

Content typeapplication/json

{…}

"statusCode": 400,

"message": "Invalid arguments",

"errorCode": "1011",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 401,

"message": "Access token not valid",

"errorCode": "1300",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 402,

"message": "License expired. Please contact isv-api-contact@portatour.com.",

"errorCode": "1159",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 403,

"message": "The provided access token cannot be used for the given operation or in the given context.",

"errorCode": "1304",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 404,

"message": "Resource not found",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 409,

"message": "Calculation of a schedule is currently running.",

"errorCode": "1213",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 413,

"message": "Content too large",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 429,

"message": "Too many requests",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Retrieve async schedule calculation result

GET /1.2/organizations/{organizationId}/fieldReps/{fieldRepId}/schedule/result/{calculationId}

After an asynchronous schedule calculation is started, use this method to poll the result. If the calculation is not finished, the status "Processing" will be returned.

After a successful calculation, the result remains available for 60 seconds. A polling interval of 1 second is recommended.

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}

Authorizations:AccessToken

Security scheme type: API Key

Header parameter name: pt-access-token

path parameters

organizationId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]
fieldRepId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]
calculationId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]

Responses

200 OK

Response schema: application/json

status
string
Provides information about the status of the schedule calculation. Possible values are:
- "Processing"
- "Succeeded"
- "Failed"

schedule

Schedule

Is set, when status is "Succeeded".

id
string
Unique for each calculated schedule.

days

array of ScheduleDay

The scheduled days.

day
string <yyyy-MM-dd> (IsoDateString)
Date of scheduled day.

IsoDateString is a date type that contains values in the format "yyyy-MM-dd", e.g. "2022-01-31".

rows

array of ScheduleRownullable

One row represents one scheduled item. A typical schedule has multiple rows. For example, a Drive row followed by a StopAtCustomer row and another Drive row.

type
string<= 250 characters
The row type determines which of the subsequent row fields below is set. E.g. if the type is "Drive", only the field drive is set. Possible values are:
- "Stop"
- "Drive"
- "SchedulingConstraintWithoutLocation"
stop
ScheduleStopRow
Specifies a stop. Only set if the row type is "Stop".
- timeFrom
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  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
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  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
  string
  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 type customerEvent.
  "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 type customerEvent.
  "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 type customerEvent.
  "StopAtOtherSchedulingConstraint": A stop due to a scheduling constraint that does not have a customer reference, e.g. a scheduling constraint of type blocker.
  
  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 type overnightstay.
- displayName
  string<= 1000 characters
  Name or subject of the stop.
- location
  Location
  Location of the stop.
  
  address
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
  geocodeWarning
  stringnullable
  This field is used for output-only. Do not set this field.
- customerId
  string<= 40 charactersnullable
  If the stop is associated with a customer, the customer id is provided.
- schedulingConstraintId
  string<= 40 charactersnullable
  If the stop is associated with a scheduling constraint, the scheduling constraint id is provided.
- preferredOvernightLocationId
  string<= 40 charactersnullable
  If the stop is associated with a preferred overnight location, the preferred overnight lcoation id is provided.

drive

ScheduleDriveRow

Specifies a drive. Only set if the row type is "Drive".

timeFrom
string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
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
string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
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
integer <int32>
Drive distance in meters.
routingType
string
The routingType indicates how the routing was made. Possible values are:
- "TypicalTraffic",
- "CurrentTraffic",
- "Beeline"
routePolyline
stringnullable
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 IncludeRoutePolylinesInSchedule is true in the calculationParameters.

interruption

DriveInterruption

An interruption represents a time span during which no driving takes place. It is used to model waiting periods (e.g., waiting for a customer to open) as well as work breaks.

If null, no interruption is scheduled for the drive, which is typically the case.

Example	A	B	C
`drive.timeFrom`	10:00	11:00	12:00
`drive.timeTo`	15:20	11:37	12:10
`drive.interruption.timeFrom`	12:00	11:00	12:00
`drive.interruption.timeTo`	12:45	11:30	12:06
`drive.interruption.containsWorkBreak`	true	true	false
driving duration	4h35min	7min	4min
interruption duration	45min	30min	6min

timeFrom
string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
timeTo
string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
containsWorkBreak
booleanrequired

schedulingConstraintWithoutLocation
SchedulingConstraintWithoutLocationRow
Specifies a period for a scheduling constraint without a location. Only set if the row type is "SchedulingConstraintWithoutLocation".

Note: The timeFrom and timeTo of the schedulingConstraintWithoutLocation overlaps with the timeFrom and timeTo of the previous drive in the schedule. To calculate the driving time of the preceding drive, the duration of the schedulingConstraintWithoutLocation must be added to the interruption duration, which is subtracted from the duration of the time frame during which the drive takes place.

For example, if a schedulingConstraintWithoutLocation with timeFrom of 10:30 and timeTo of 11:00 were to follow the drive from example A in the description of drive.interruption above, the 30-minute duration of the scheduling constraint would be added to the interruption duration, resulting in a total interruption duration of 75 minutes. This would shorten the driving duration to 4 hours and 5 minutes.
- timeFrom
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  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
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  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
  string<= 1000 characters
  Display name of the scheduling constraint.
- schedulingConstraintId
  string
  Id to the scheduling constraint.
- customerId
  stringnullable
  Id of the customer associated with the scheduling constraint.
  
  Note: If null, there is no customer associated with the scheduling constraint.

messages
array of ScheduleMessagenullable
Provide information about the schedule. The possible messages are documented in the schedule messages section.

Note: If null, there are no messages.
- messageId
  string
  Identifies the schedule message.
- severity
  string<= 250 characters
  The severity level of the message. Possible values are:
  
  "Info"
  "Warning"
  "Error"
- text
  string<= 1000 characters
  Is provided in the language of the field rep. Its content is described in the schedule message description.
deviations
Deviations
Deviations of the calculated schedule from the input data used for schedule calculation.

Note: If null, there are no deviations.
- unscheduledSchedulingConstraintsInSchedulePeriod
  array of stringnullable
  List of ids of scheduling constraints that were not scheduled. If not null, the schedule will include messages with id 5048 or id 5050.
  
  Possible reasons:
  
  The scheduling constraint collides with another of your scheduling constraints. Either the scheduling constraints overlap or the time between the scheduling constraints is not sufficient for the required drive from the first to the second scheduling constraint.
  The scheduling constraint is located far away from your starting point or it takes too long to get there, undertake the scheduling constraint and drive back to the home location all within one day.
- unscheduledCustomersWithDoForceCall
  array of stringnullable
  List of ids of customers with doForceCall set that were not scheduled. If not null, the schedule will include a message with id 5049.
  
  Possible reasons:
  
  There are too many customers with doForceCall set and not all of them can be included in the schedule.
  A customer has no or very limited business hours, which are either outside of the field rep's working hours or in conflict with the limited business hours of a different customer with doForceCall or with a scheduling constraint.
  A customer is located far away from your home location so that they cannot be reached within the working hours.
  A customer has no address information or the address could not be geocoded.
- schedulingConstraintsWithDeviatingTime
  array of stringnullable
  List of ids of scheduling constraints that have a deviating time. Scheduling constraints with a deviating time can be either shortened or postponed. If not null, the schedule will include messages with id 5003 or id 5042.
  
  Possible reason for shortening:
  
  To ensure there is enough time to reach a following scheduling constraint on time.
  
  Possible reason for postponement:
  
  To ensure there is enough time to reach the first scheduling constraint of the schedule.

errorCode
string<= 250 charactersnullable
Is set, when status is "Failed". Identifies the schedule calculation error. The possible errors are documented in the schedule error codes section.
errorMessage
string<= 1000 charactersnullable
Is set, when status is "Failed". Describes the schedule calculation error. The possible errors are documented in the schedule error codes section.

Error responses (10)

400 Bad Request

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

401 Unauthorized

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

402 Payment Required

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

403 Forbidden

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

404 Not Found

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

409 Conflict

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

413 Content Too Large

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

429 Too Many Requests

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

500 Internal ServerError

503 Service Unavailable

Response samples

200400401402403404409413429

Content typeapplication/json

{…}

"status": "Succeeded",

"schedule": {…}

"id": "{CB0B35B5-DC10-4F79-88BA-3CB5904EBDDD}",

"days": […]

{…}

"day": "2026-09-17",

"rows": […]

{…}

"type": "Stop",

"stop": {…}

"timeFrom": "08:00:00",

"timeTo": "08:00:00",

"stopType": "DepartureFromHome",

"displayName": "Home location",

"location": {…}

"address": {…}

"streetWithHouseNumber": "5366 College Ave",

"postalCode": "94618",

"city": "Oakland",

"state": "CA",

"country": "US"

"geoPosition": {…}

"latitude": 37.839302,

"longitude": -122.25132

}

{…}

"type": "Drive",

"drive": {…}

"timeFrom": "08:00:00",

"timeTo": "08:38:12",

"distanceMeters": 31122,

"routingType": "TypicalTraffic",

}

{…}

"type": "Stop",

"stop": {…}

"timeFrom": "08:38:12",

"timeTo": "09:08:12",

"stopType": "StopAtCustomer",

"displayName": "Clark, Allison",

"location": {…}

"address": {…}

"streetWithHouseNumber": "1101 Alberta Way",

"postalCode": "94521-3799",

"city": "Concord",

"state": "CA",

"country": "US"

"geoPosition": {…}

"latitude": 37.94825,

"longitude": -121.96817

}

"customerId": "aa14d116f577448a9b307ba11f47630b"

}

… 16 more items, use Copy for the full sample

]

{…}

"day": "2026-09-18",

"rows": […]

{…}

"type": "Stop",

"stop": {…}

"timeFrom": "08:00:00",

"timeTo": "08:00:00",

"stopType": "DepartureFromHome",

"displayName": "Home location",

"location": {…}

"address": {…}

"streetWithHouseNumber": "5366 College Ave",

"postalCode": "94618",

"city": "Oakland",

"state": "CA",

"country": "US"

"geoPosition": {…}

"latitude": 37.839302,

"longitude": -122.25132

}

{…}

"type": "Drive",

"drive": {…}

"timeFrom": "08:00:00",

"timeTo": "08:36:54",

"distanceMeters": 38430,

"routingType": "TypicalTraffic",

}

{…}

"type": "Stop",

"stop": {…}

"timeFrom": "08:36:54",

"timeTo": "09:36:54",

"stopType": "StopAtCustomer",

"displayName": "Allen, Crystal",

"location": {…}

"address": {…}

"streetWithHouseNumber": "160-B North San Pedro Road",

"postalCode": "94903",

"city": "San Rafael",

"state": "CA",

"country": "US"

"geoPosition": {…}

"latitude": 37.99927,

"longitude": -122.52507

}

"customerId": "90833a0467e84552bfcf4453eca2e06e"

}

… 12 more items, use Copy for the full sample

]

{…}

"day": "2026-09-19",

"rows": […]

{…}

"type": "Stop",

"stop": {…}

"timeFrom": "07:30:06",

"timeTo": "07:30:06",

"stopType": "DepartureFromPreferredOvernightLocation",

"displayName": "Overnight stay Best Western Plus Garden Inn - Santa Rosa",

"location": {…}

"address": {…}

"streetWithHouseNumber": "1500 Santa Rosa Avenue",

"postalCode": "95404",

"city": "Santa Rosa",

"state": "CA",

"country": "US"

"geoPosition": {…}

"latitude": 38.42383,

"longitude": -122.71344

}

"preferredOvernightLocationId": "223b848cc7b44a52af0fd991e4eee6ad"

}

{…}

"type": "Drive",

"drive": {…}

"timeFrom": "07:30:06",

"timeTo": "08:00:59",

"distanceMeters": 35783,

"routingType": "TypicalTraffic",

}

{…}

"type": "Stop",

"stop": {…}

"timeFrom": "08:00:59",

"timeTo": "08:30:00",

"stopType": "StopAtCustomerSchedulingConstraint",

"displayName": "Pérez, Kyle",

"location": {…}

"address": {…}

"streetWithHouseNumber": "140 2nd St",

"postalCode": "94971",

"city": "Tomales",

"state": "California",

"country": "USA"

"geoPosition": {…}

"latitude": 38.46104,

"longitude": -122.93607

}

"customerId": "a54bb393d0944271b36ea04172018201",

"schedulingConstraintId": "17574c0ae9d9456ab03e57ea4bd10b5a"

}

… 14 more items, use Copy for the full sample

]

… 2 more items, use Copy for the full sample

"messages": []

}

Content typeapplication/json

{…}

"statusCode": 400,

"message": "Invalid arguments",

"errorCode": "1011",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 401,

"message": "Access token not valid",

"errorCode": "1300",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 402,

"message": "License expired. Please contact isv-api-contact@portatour.com.",

"errorCode": "1159",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 403,

"message": "The provided access token cannot be used for the given operation or in the given context.",

"errorCode": "1304",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 404,

"message": "Resource not found",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 409,

"message": "Calculation of a schedule is currently running.",

"errorCode": "1213",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 413,

"message": "Content too large",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 429,

"message": "Too many requests",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Access Tokens

All access tokens may be created, listed and revoked in the portatour® Partner Portal.

Access tokens expire six months after their last use. The expiration date of tokens is automatically extended to six months upon use.

Using the ISV API you can create organization and field rep level access tokens.

Note: Even though access tokens may be listed in the Partner Portal, it is not possible to later retrieve the token value of any access token. It is therefore your responsibility to store the returned tokenValue after creation.

See the list of possible errors that can occur during the execution of access token operations.

Create an access token for an organization

POST /1.2/organizations/{organizationId}/accessTokens

Create an access token for the given organization. Access token creation is limited to 10 per organization within 24 hours.

This method requires an access token of scope:

Partner access token

Authorizations:AccessToken

Security scheme type: API Key

Header parameter name: pt-access-token

path parameters

organizationId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]

Responses

200 OK

Response schema: application/json

tokenValue
string
Access token value.
publicId
string
Public id of the access token.

Error responses (10)

400 Bad Request

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

401 Unauthorized

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

402 Payment Required

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

403 Forbidden

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

404 Not Found

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

409 Conflict

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

413 Content Too Large

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

429 Too Many Requests

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

500 Internal ServerError

503 Service Unavailable

Response samples

200400401402403404409413429

Content typeapplication/json

{…}

"tokenValue": "9ZF5v3hcXutg0-SW4zUA5sgC.2ciehqJb-gW-hpAWq8vJwhWM",

"publicId": "9ZF5v3hcXutg0-SW4zUA5sgC"

}

Content typeapplication/json

{…}

"statusCode": 400,

"message": "Invalid arguments",

"errorCode": "1011",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 401,

"message": "Access token not valid",

"errorCode": "1300",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 402,

"message": "License expired. Please contact isv-api-contact@portatour.com.",

"errorCode": "1159",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 403,

"message": "The provided access token cannot be used for the given operation or in the given context.",

"errorCode": "1304",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 404,

"message": "Resource not found",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 409,

"message": "Calculation of a schedule is currently running.",

"errorCode": "1213",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 413,

"message": "Content too large",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 429,

"message": "Too many requests",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Create an access token for a field rep

POST /1.2/organizations/{organizationId}/fieldReps/{fieldRepId}/accessTokens

Create an access token for the given field rep of an organization. Access tokens can only be created for existing field reps. Access token creation is limited to 10 per field rep within 24 hours.

This method requires an access token with either of the following scopes:

Partner access token
Organization access token for {organizationId}

Authorizations:AccessToken

Security scheme type: API Key

Header parameter name: pt-access-token

path parameters

organizationId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]
fieldRepId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]

Responses

200 OK

Response schema: application/json

tokenValue
string
Access token value.
publicId
string
Public id of the access token.

Error responses (10)

400 Bad Request

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

401 Unauthorized

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

402 Payment Required

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

403 Forbidden

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

404 Not Found

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

409 Conflict

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

413 Content Too Large

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

429 Too Many Requests

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

500 Internal ServerError

503 Service Unavailable

Response samples

200400401402403404409413429

Content typeapplication/json

{…}

"tokenValue": "9ZF5v3hcXutg0-SW4zUA5sgC.2ciehqJb-gW-hpAWq8vJwhWM",

"publicId": "9ZF5v3hcXutg0-SW4zUA5sgC"

}

Content typeapplication/json

{…}

"statusCode": 400,

"message": "Invalid arguments",

"errorCode": "1011",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 401,

"message": "Access token not valid",

"errorCode": "1300",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 402,

"message": "License expired. Please contact isv-api-contact@portatour.com.",

"errorCode": "1159",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 403,

"message": "The provided access token cannot be used for the given operation or in the given context.",

"errorCode": "1304",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 404,

"message": "Resource not found",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 409,

"message": "Calculation of a schedule is currently running.",

"errorCode": "1213",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 413,

"message": "Content too large",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 429,

"message": "Too many requests",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Revoke an existing access token

DELETE /1.2/accessTokens/{publicId}

Revoke an existing access token. Access tokens are allowed to revoke themselves. Tokens of higher scopes may revoke tokens of lower scope.

A field rep access token can be revoked by itself, a token of its organization or its partner.
An organization access token can be revoked by itself or a token of its partner.
A partner access token can be revoked by itself or another token of the partner.

Authorizations:AccessToken

Security scheme type: API Key

Header parameter name: pt-access-token

path parameters

publicId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]

Responses

204 No Content

Error responses (10)

400 Bad Request

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

401 Unauthorized

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

402 Payment Required

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

403 Forbidden

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

404 Not Found

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

409 Conflict

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

413 Content Too Large

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

429 Too Many Requests

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

500 Internal ServerError

503 Service Unavailable

Response samples

400401402403404409413429

Content typeapplication/json

{…}

"statusCode": 400,

"message": "Invalid arguments",

"errorCode": "1011",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 401,

"message": "Access token not valid",

"errorCode": "1300",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 402,

"message": "License expired. Please contact isv-api-contact@portatour.com.",

"errorCode": "1159",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 403,

"message": "The provided access token cannot be used for the given operation or in the given context.",

"errorCode": "1304",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 404,

"message": "Resource not found",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 409,

"message": "Calculation of a schedule is currently running.",

"errorCode": "1213",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 413,

"message": "Content too large",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 429,

"message": "Too many requests",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Organizations

Before uploading any field rep data you must create an organization.

Note: It is not possible to create or update multiple organizations for the same partner in parallel. Parallel requests will result in a conflict HTTP status response.

See the list of possible errors that can occur when creating organizations.

Add or update an organization

PUT /1.2/organizations/{organizationId}

This method requires an access token with scope:

Partner access token

Authorizations:AccessToken

Security scheme type: API Key

Header parameter name: pt-access-token

path parameters

organizationId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]

Request body schema: application/json

Parameters that are needed to create an organizations

name
stringrequired[ 1 .. 250 ] characters
Name of the organization.
edition
stringrequirednon-empty
Determines feature and capacity limits. The following editions are supported:
- "Basic"
- "Professional"
- "Ultimate"
Note: The edition selected will affect the features and limits available to that organization. Different credits will be charged depending on the edition selected. You can upgrade or downgrade your edition at any time.
mapRegion
stringrequired[ 0 .. 250 ] characters
Defines the continent used for the organization. Each organization is assigned to exactly one map region. The available map regions are:
- "Europe"
- "LatinAmerica"
- "MiddleEastAndAfrica"
- "NorthAmerica"
- "Oceania"
maxFieldRepCount
integer <int32>required[ 1 .. 1000 ]
Defines the maximum number of field reps for the organization.
enabledUntilUTC
string <yyyy-MM-ddTHH:mm> (IsoDateTimeStringMinutesPrecision)required
Determines how long the organization may be used. The value can be set to any value starting 24 hours in the past. There is no restriction on future date values.

IsoDateTimeStringMinutesPrecision is a DateTime type that contains values in the format "yyyy-MM-ddTHH:mm", e.g. "2022-01-31T23:59".

Responses

200 OK

Error responses (10)

400 Bad Request

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

401 Unauthorized

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

402 Payment Required

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

403 Forbidden

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

404 Not Found

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

409 Conflict

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

413 Content Too Large

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

429 Too Many Requests

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

500 Internal ServerError

503 Service Unavailable

Request samples

Payload

Content typeapplication/json

{…}

"name": "Example Inc.",

"edition": "Ultimate",

"mapRegion": "Europe",

"maxFieldRepCount": 10,

"enabledUntilUTC": "2026-12-16T23:57"

}

Response samples

400401402403404409413429

Content typeapplication/json

{…}

"statusCode": 400,

"message": "Invalid arguments",

"errorCode": "1011",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 401,

"message": "Access token not valid",

"errorCode": "1300",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 402,

"message": "License expired. Please contact isv-api-contact@portatour.com.",

"errorCode": "1159",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 403,

"message": "The provided access token cannot be used for the given operation or in the given context.",

"errorCode": "1304",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 404,

"message": "Resource not found",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 409,

"message": "Calculation of a schedule is currently running.",

"errorCode": "1213",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 413,

"message": "Content too large",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 429,

"message": "Too many requests",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Geocode

Geocoding refers to finding the geoposition (latitude and longitude) for a given text address. Reverse geocoding finds the closest address for a given geoposition. Geocoding operations may be synchronous or asynchronous.

Geocode

POST /1.2/organizations/{organizationId}/fieldReps/{fieldRepId}/geocode

Geocode multiple addresses (max. 2,000 per request) blocks until completion. The result list will be in the same order as the input addresses.

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}

Authorizations:AccessToken

Security scheme type: API Key

Header parameter name: pt-access-token

path parameters

organizationId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]
fieldRepId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
The id of the field rep.

An id must consist of the following characters: [a-zA-Z0-9-_{}]

Request body schema: application/json

The addresses to geocode.

Array of Address

streetWithHouseNumber
string<= 250 charactersnullable
Contains the street and the house number of the address. Do not use if singleLineAddress is set.

Example for Germany:
- Jahnstr. 18
Example for USA:
- 140 2nd St
postalCode
string<= 250 charactersnullable
Contains the postal code of the address. Do not use if singleLineAddress is set.
city
string<= 250 charactersnullable
Contains the city of the address. Do not use if singleLineAddress is set.
state
string<= 250 charactersnullable
Contains the state of the address. Do not use if singleLineAddress is set.
country
string<= 250 charactersnullable
Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.

Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
singleLineAddress
string<= 1000 charactersnullable
Note: This field is used for input-only and will never be returned.

The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.

You cannot use the other address properties apart from country if this property is set.

Responses

200 OK

Response schema: application/json

Array of Location

address
Address
- streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
- postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
- city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
- state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
- country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
- singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
geoPosition
GeoPosition
WGS84 (EPSG:4326) coordinates of the geoposition.
- latitude
  number <double>required[ -90 .. 90 ]
- longitude
  number <double>required[ -180 .. 180 ]
- geocodeWarning
  stringnullable
  This field is used for output-only. Do not set this field.

Error responses (10)

400 Bad Request

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

401 Unauthorized

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

402 Payment Required

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

403 Forbidden

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

404 Not Found

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

409 Conflict

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

413 Content Too Large

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

429 Too many requests.

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

500 Internal ServerError

503 Service Unavailable

Request samples

Payload

Content typeapplication/json

[…]

{…}

"streetWithHouseNumber": "140 2nd St",

"postalCode": "94971",

"city": "Tomales",

"state": "California",

"country": "USA"

}

]

Response samples

200400401402403404409413429

Content typeapplication/json

[…]

{…}

"address": {…}

"streetWithHouseNumber": "140 2nd St",

"postalCode": "94971",

"city": "Tomales",

"state": "California",

"country": "USA"

"geoPosition": {…}

"latitude": 38.248,

"longitude": -122.9055

}

]

Content typeapplication/json

{…}

"statusCode": 400,

"message": "Invalid arguments",

"errorCode": "1011",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 401,

"message": "Access token not valid",

"errorCode": "1300",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 402,

"message": "License expired. Please contact isv-api-contact@portatour.com.",

"errorCode": "1159",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 403,

"message": "The provided access token cannot be used for the given operation or in the given context.",

"errorCode": "1304",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 404,

"message": "Resource not found",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 409,

"message": "Calculation of a schedule is currently running.",

"errorCode": "1213",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 413,

"message": "Content too large",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 429,

"message": "Too many requests",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Reverse geocode

POST /1.2/organizations/{organizationId}/fieldReps/{fieldRepId}/geocode/reverse

Find the closest address to a single geoposition.

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}

Authorizations:AccessToken

Security scheme type: API Key

Header parameter name: pt-access-token

path parameters

organizationId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]
fieldRepId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
The id of the field rep.

An id must consist of the following characters: [a-zA-Z0-9-_{}]

Request body schema: application/json

The geoposition that should be reverse geocoded.

latitude
number <double>required[ -90 .. 90 ]
longitude
number <double>required[ -180 .. 180 ]

Responses

200 OK

Response schema: application/json

address
AddressExport
- streetWithHouseNumber
  string
  Street and house number of the address.
- postalCode
  string
  Postal code of the address.
- city
  string
  City of the address.
- state
  stringnullable
  State of the address.
- country
  string
  Country of the address.
geoPosition
GeoPositionExport
WGS84 (EPSG:4326) coordinates of the geoposition.
- latitude
  number <double>[ -90 .. 90 ]
- longitude
  number <double>[ -180 .. 180 ]
- geocodeWarning
  stringnullable
  If latitude and longitude are 0, there is a description of the geocode problem. If latitude and longitude are set and there is a geocode warning, the warning is provided.

Error responses (10)

400 Bad Request

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

401 Unauthorized

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

402 Payment Required

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

403 Forbidden

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

404 Not Found

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

409 Conflict

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

413 Content Too Large

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

429 Too many requests.

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

500 Internal ServerError

503 Service Unavailable

Request samples

Payload

Content typeapplication/json

{…}

"latitude": 38.248,

"longitude": -122.9055

}

Response samples

200400401402403404409413429

Content typeapplication/json

{…}

"address": {…}

"streetWithHouseNumber": "140 2nd St",

"postalCode": "94971",

"city": "Tomales",

"state": "California",

"country": "USA"

"geoPosition": {…}

"latitude": 38.248,

"longitude": -122.9055

}

Content typeapplication/json

{…}

"statusCode": 400,

"message": "Invalid arguments",

"errorCode": "1011",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 401,

"message": "Access token not valid",

"errorCode": "1300",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 402,

"message": "License expired. Please contact isv-api-contact@portatour.com.",

"errorCode": "1159",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 403,

"message": "The provided access token cannot be used for the given operation or in the given context.",

"errorCode": "1304",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 404,

"message": "Resource not found",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 409,

"message": "Calculation of a schedule is currently running.",

"errorCode": "1213",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 413,

"message": "Content too large",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 429,

"message": "Too many requests",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Async geocode

POST /1.2/organizations/{organizationId}/fieldReps/{fieldRepId}/geocode/start

This method starts a geocoding calculation task for multiple addresses (max. 2,000 per request). The current status of the operation can be polled using retrieve geocoding result and the returned geocodeTaskId. Alternatively use the URL returned in the "location" HTTP response header.

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}

Authorizations:AccessToken

Security scheme type: API Key

Header parameter name: pt-access-token

path parameters

organizationId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]
fieldRepId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
The id of the field rep.

An id must consist of the following characters: [a-zA-Z0-9-_{}]

Request body schema: application/json

The list of address that should be geocoded.

Array of Address

streetWithHouseNumber
string<= 250 charactersnullable
Contains the street and the house number of the address. Do not use if singleLineAddress is set.

Example for Germany:
- Jahnstr. 18
Example for USA:
- 140 2nd St
postalCode
string<= 250 charactersnullable
Contains the postal code of the address. Do not use if singleLineAddress is set.
city
string<= 250 charactersnullable
Contains the city of the address. Do not use if singleLineAddress is set.
state
string<= 250 charactersnullable
Contains the state of the address. Do not use if singleLineAddress is set.
country
string<= 250 charactersnullable
Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.

Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
singleLineAddress
string<= 1000 charactersnullable
Note: This field is used for input-only and will never be returned.

The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.

You cannot use the other address properties apart from country if this property is set.

Responses

202 Accepted

Response schema: application/json

geocodeTaskId
stringnullable
Is used to retrieve the geocode result.

Error responses (10)

400 Bad Request

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

401 Unauthorized

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

402 Payment Required

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

403 Forbidden

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

404 Not Found

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

409 Conflict

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

413 Content Too Large

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

429 Too many requests.

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

500 Internal ServerError

503 Service Unavailable

Request samples

Payload

Content typeapplication/json

[…]

{…}

"streetWithHouseNumber": "140 2nd St",

"postalCode": "94971",

"city": "Tomales",

"state": "California",

"country": "USA"

}

]

Response samples

202400401402403404409413429

Content typeapplication/json

{…}

"geocodeTaskId": "{30AD8A3B-0C94-48ED-85C9-24020870945A}"

}

Content typeapplication/json

{…}

"statusCode": 400,

"message": "Invalid arguments",

"errorCode": "1011",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 401,

"message": "Access token not valid",

"errorCode": "1300",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 402,

"message": "License expired. Please contact isv-api-contact@portatour.com.",

"errorCode": "1159",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 403,

"message": "The provided access token cannot be used for the given operation or in the given context.",

"errorCode": "1304",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 404,

"message": "Resource not found",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 409,

"message": "Calculation of a schedule is currently running.",

"errorCode": "1213",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 413,

"message": "Content too large",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 429,

"message": "Too many requests",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Async geocode result

GET /1.2/organizations/{organizationId}/fieldReps/{fieldRepId}/geocode/result/{geocodeTaskId}

After an asynchronous geocoding operation is started, use this method to retrieve the result. If the result is not ready the status "Processing" will be returned instead.

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}

Authorizations:AccessToken

Security scheme type: API Key

Header parameter name: pt-access-token

path parameters

organizationId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]
fieldRepId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]
geocodeTaskId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]

Responses

200 OK

Response schema: application/json

status
string
Provides information about the geocoding status. Possible values are:
- "Processing"
- "Succeeded"
locations
array of Locationnullable
Is set, when status is "Succeeded". Is the list of the geocoded locations.
- address
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
- geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
  geocodeWarning
  stringnullable
  This field is used for output-only. Do not set this field.

Error responses (10)

400 Bad Request

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

401 Unauthorized

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

402 Payment Required

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

403 Forbidden

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

404 Not Found

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

409 Conflict

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

413 Content Too Large

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

429 Too many requests.

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

500 Internal ServerError

503 Service Unavailable

Response samples

200400401402403404409413429

Content typeapplication/json

{…}

"status": "Succeeded",

"locations": […]

{…}

"address": {…}

"streetWithHouseNumber": "140 2nd St",

"postalCode": "94971",

"city": "Tomales",

"state": "California",

"country": "USA"

"geoPosition": {…}

"latitude": 38.248,

"longitude": -122.9055

}

]

}

Content typeapplication/json

{…}

"statusCode": 400,

"message": "Invalid arguments",

"errorCode": "1011",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 401,

"message": "Access token not valid",

"errorCode": "1300",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 402,

"message": "License expired. Please contact isv-api-contact@portatour.com.",

"errorCode": "1159",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 403,

"message": "The provided access token cannot be used for the given operation or in the given context.",

"errorCode": "1304",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 404,

"message": "Resource not found",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 409,

"message": "Calculation of a schedule is currently running.",

"errorCode": "1213",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 413,

"message": "Content too large",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 429,

"message": "Too many requests",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Field Reps

After creating an organization the next step is creating and uploading field rep data including the field rep's customers' data. Field reps must be created via the AddOrUpdate call first, while customer data may alternatively be passed to the calculateSchedule call directly.

See the list of possible errors that can occur during the execution of field reps operations.

Add or update a field rep

PUT /1.2/organizations/{organizationId}/fieldReps/{fieldRepId}

Create or update a single field rep. Each physical field rep must be represented by one corresponding entry. The given fieldRepId is provided by you and must be unique for the organization.

Creating a field rep is only allowed for partner and organization level access tokens.
Using a field rep access token you can update any attribute except for the name.

This method requires an access token with one of the following scopes:

Partner access token
Organization access token access token for {organizationId}
FieldRep access token access token for {fieldRepId}(update only)

Authorizations:AccessToken

Security scheme type: API Key

Header parameter name: pt-access-token

path parameters

organizationId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]
fieldRepId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
The fieldRepId is part of the URL and must not be passed in the body data.

An id must consist of the following characters: [a-zA-Z0-9-_{}]

Request body schema: application/json

name
stringrequired[ 1 .. 250 ] characters
The full name of the field rep.
languageCultureName
stringrequirednon-empty^[a-z]{2}-[A-Z]{2}$
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
HomeLocationrequired
Specify address and/or geoPosition. If both are specified, the geoPosition is used as the location. If only the address is 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
  HomeAddress
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  stringrequired[ 1 .. 250 ] characters
  Contains the country of the address. This property is required, even if singleLineAddress is set. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
- geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
workingHours
WorkingHours
Defines the hours per weekday that a field rep works. At least one day must be set.
- monday
  DailyTimeRange
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
- tuesday
  DailyTimeRange
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
- wednesday
  DailyTimeRange
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
- thursday
  DailyTimeRange
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
- friday
  DailyTimeRange
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
- saturday
  DailyTimeRange
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
- sunday
  DailyTimeRange
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
drivingTimeFactors
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.

Edition: Ultimate
- cityRoad
  number <double>[ 0.5 .. 2 ]
  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
  number <double>[ 0.5 .. 2 ]
  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
  number <double>[ 0.5 .. 2 ]
  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
OvernightStayAwayFromHomeSettings
Defines the conditions for overnight stays away from home.

Note: If this property is not set, no overnight stays are scheduled.

Edition: Ultimate
- isAllowedOnMonday
  booleannullable
  Specifies whether overnight stays away from home are allowed on Mondays.
  
  Default: false
- isAllowedOnTuesday
  booleannullable
  Specifies whether overnight stays away from home are allowed on Tuesdays.
  
  Default: false
- isAllowedOnWednesday
  booleannullable
  Specifies whether overnight stays away from home are allowed on Wednesdays.
  
  Default: false
- isAllowedOnThursday
  booleannullable
  Specifies whether overnight stays away from home are allowed on Thursdays.
  
  Default: false
- isAllowedOnFriday
  booleannullable
  Specifies whether overnight stays away from home are allowed on Fridays
  
  Default: false
- isAllowedOnSaturday
  booleannullable
  Specifies whether overnight stays away from home are allowed on Saturdays.
  
  Default: false
- isAllowedOnSunday
  booleannullable
  Specifies whether overnight stays away from home are allowed on Sundays.
  
  Default: false
- minimumMetersFromHome
  integer <int32>[ 0 .. 999000 ]nullable
  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
  integer <int32>[ 0 .. 999 ]nullable
  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
  integer <int32>[ 0 .. 999 ]nullable
  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
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
  number <double>[ 0 .. 100 ]
  Specifies the value (in %) of the elapsed call interval after which the next call can be scheduled.
  
  Default: 70
- adherenceToCallingHours
  string
  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
WorkBreak
Specifies how to schedule a work break.

Note: If this property is null, no break is scheduled.
- scheduleWithin
  TimeRangerequired
  The time range consists of the from time and the to time.
  
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
- durationMinutes
  integer <int32>required^[0-9]\d*$
  Specifies the duration of the work break in minutes. The duration must fit within scheduleWithin.

Responses

200 OK

Error responses (10)

400 Bad Request

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

401 Unauthorized

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

402 Payment Required

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

403 Forbidden

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

404 Not Found

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

409 Conflict

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

413 Content Too Large

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

429 Too many requests.

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

500 Internal ServerError

503 Service Unavailable

Request samples

Payload

Content typeapplication/json

{…}

"name": "Alice",

"languageCultureName": "en-US",

"homeLocation": {…}

"address": {…}

"streetWithHouseNumber": "5366 College Ave",

"postalCode": "94618",

"city": "Oakland",

"state": "CA",

"country": "US"

"geoPosition": {…}

"latitude": 37.839302,

"longitude": -122.25132

}

"workingHours": {…}

"monday": {…}

"from": "08:00:00",

"to": "18:00:00"

"tuesday": {…}

"from": "08:00:00",

"to": "18:00:00"

"wednesday": {…}

"from": "08:00:00",

"to": "18:00:00"

"thursday": {…}

"from": "08:00:00",

"to": "18:00:00"

"friday": {…}

"from": "08:00:00",

"to": "18:00:00"

}

"drivingTimeFactors": {…}

"cityRoad": 1,

"countryRoad": 1,

"highway": 1

"overnightStayAwayFromHomeSettings": {…}

"isAllowedOnMonday": true,

"isAllowedOnTuesday": true,

"isAllowedOnWednesday": true,

"isAllowedOnThursday": true,

"isAllowedOnFriday": false,

"isAllowedOnSaturday": false,

"isAllowedOnSunday": false

"generalCustomerSchedulingSettings": {…}

"dueAfterLastCallIntervalPercent": 70,

"adherenceToCallingHours": "StartOfCall"

"workBreak": {…}

"scheduleWithin": {…}

"from": "12:00:00",

"to": "13:00:00"

"durationMinutes": 30

}

Response samples

400401402403404409413429

Content typeapplication/json

{…}

"statusCode": 400,

"message": "Invalid arguments",

"errorCode": "1011",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 401,

"message": "Access token not valid",

"errorCode": "1300",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 402,

"message": "License expired. Please contact isv-api-contact@portatour.com.",

"errorCode": "1159",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 403,

"message": "The provided access token cannot be used for the given operation or in the given context.",

"errorCode": "1304",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 404,

"message": "Resource not found",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 409,

"message": "Calculation of a schedule is currently running.",

"errorCode": "1213",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 413,

"message": "Content too large",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 429,

"message": "Too many requests",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Delete a field rep

DELETE /1.2/organizations/{organizationId}/fieldReps/{fieldRepId}

This method requires an access token with one of the following scopes:

Partner access token
Organization access token for {organizationId}

Authorizations:AccessToken

Security scheme type: API Key

Header parameter name: pt-access-token

path parameters

organizationId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]
fieldRepId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]

Responses

204 No Content

Error responses (10)

400 Bad Request

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

401 Unauthorized

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

402 Payment Required

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

403 Forbidden

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

404 Not Found

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

409 Conflict

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

413 Content Too Large

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

429 Too many requests.

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

500 Internal ServerError

503 Service Unavailable

Response samples

400401402403404409413429

Content typeapplication/json

{…}

"statusCode": 400,

"message": "Invalid arguments",

"errorCode": "1011",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 401,

"message": "Access token not valid",

"errorCode": "1300",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 402,

"message": "License expired. Please contact isv-api-contact@portatour.com.",

"errorCode": "1159",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 403,

"message": "The provided access token cannot be used for the given operation or in the given context.",

"errorCode": "1304",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 404,

"message": "Resource not found",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 409,

"message": "Calculation of a schedule is currently running.",

"errorCode": "1213",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 413,

"message": "Content too large",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 429,

"message": "Too many requests",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Set customers

PUT /1.2/organizations/{organizationId}/fieldReps/{fieldRepId}/customers

Replace the entire set of customers of a single field rep.

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}

The allowed number of customers, depending on the Edition, are

Basic: 125
Professional: 500
Ultimate: 1000

Authorizations:AccessToken

Security scheme type: API Key

Header parameter name: pt-access-token

path parameters

organizationId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]
fieldRepId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]

Request body schema: application/json

All customers of the field rep.

Array of Customer

id
stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
name
stringrequired[ 1 .. 250 ] characters
The name of the customer.
location
Locationrequired
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
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
- geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
activatedOn
string <yyyy-MM-dd> (IsoDateString)required
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
string <yyyy-MM-dd> (IsoDateString)nullable
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's dueAfterLastCallIntervalPercent must be reached. Must not be earlier than activatedOn.

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
string <yyyy-MM-dd> (IsoDateString)nullable
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
CallInterval
Specifies the interval at which the customer should be called.

Note: If null, the customer has no call interval.
- days
  integer <int32>[ 7 .. 730 ]nullable
  The customer's call interval in days. A next call can be scheduled when the dueAfterLastCallIntervalPercent since the last call is reached.
  
  Default: 30
- isAdherencePreferred
  booleannullable
  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
integer <int32>[ 1 .. 480 ]nullable
The duration of a call in minutes.

Default: 20
schedulingRestriction
stringnullable
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.

Edition: Ultimate
doForceCall
booleannullable
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
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 isPreferred flag to true for these periods. Preferred periods cause portatour® to schedule the customer preferably within this period.

The field rep's adherenceToCallingHours in generalCustomerSchedulingSettings specifies 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.

Editions: Professional, Ultimate
- mondayPeriod1
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
- mondayPeriod2
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
- tuesdayPeriod1
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
- tuesdayPeriod2
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
- wednesdayPeriod1
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
- wednesdayPeriod2
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
- thursdayPeriod1
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
- thursdayPeriod2
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
- fridayPeriod1
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
- fridayPeriod2
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
- saturdayPeriod1
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
- saturdayPeriod2
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
- sundayPeriod1
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
- sundayPeriod2
  DailyCallingHours
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "00:00:00"
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)required
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  Default: "23:59:00"
  isPreferred
  boolean
  Edition: Ultimate
  
  Default: false
callBlocks
array of CallBlocknullable
Used to block calls from being scheduled for the customer on the specified days, e.g. the customer's holidays.

Editions: Professional, Ultimate
- beginOn
  string <yyyy-MM-dd> (IsoDateString)required
  IsoDateString is a date type that contains values in the format "yyyy-MM-dd", e.g. "2022-01-31".
- endOn
  string <yyyy-MM-dd> (IsoDateString)required
  IsoDateString is a date type that contains values in the format "yyyy-MM-dd", e.g. "2022-01-31".
- description
  string<= 250 charactersnullable

Responses

200 OK

Error responses (10)

400 Bad Request

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

401 Unauthorized

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

402 Payment Required

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

403 Forbidden

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

404 Not Found

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

409 Conflict

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

413 Content Too Large

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

429 Too many requests.

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

500 Internal ServerError

503 Service Unavailable

Request samples

Payload

Content typeapplication/json

[…]

{…}

"id": "16ff46b54c9047faaa35ecc78e490ae0",

"name": "Williams, Derek",

"location": {…}

"address": {…}

"streetWithHouseNumber": "140 2nd St",

"postalCode": "94971",

"city": "Tomales",

"state": "California",

"country": "USA"

"geoPosition": {…}

"latitude": 38.248,

"longitude": -122.9055

}

"activatedOn": "2021-10-24",

"lastCallOn": "2022-11-13",

"callInterval": {…}

"days": 30,

"isAdherencePreferred": false

"callDurationMinutes": 15,

"doForceCall": false,

"callingHours": {…}

"tuesdayPeriod1": {…}

"from": "07:00:00",

"to": "12:00:00"

"wednesdayPeriod1": {…}

"from": "07:00:00",

"to": "12:00:00"

"thursdayPeriod1": {…}

"from": "07:00:00",

"to": "12:00:00"

}

"callBlocks": […]

{…}

"beginOn": "2026-09-17",

"endOn": "2026-10-01",

"description": "Holiday"

}

]

}

]

Response samples

400401402403404409413429

Content typeapplication/json

{…}

"statusCode": 400,

"message": "Invalid arguments",

"errorCode": "1011",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 401,

"message": "Access token not valid",

"errorCode": "1300",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 402,

"message": "License expired. Please contact isv-api-contact@portatour.com.",

"errorCode": "1159",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 403,

"message": "The provided access token cannot be used for the given operation or in the given context.",

"errorCode": "1304",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 404,

"message": "Resource not found",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 409,

"message": "Calculation of a schedule is currently running.",

"errorCode": "1213",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 413,

"message": "Content too large",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 429,

"message": "Too many requests",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Set preferred overnight locations

PUT /1.2/organizations/{organizationId}/fieldReps/{fieldRepId}/preferredOvernightLocations

Replace the entire set of preferred overnight locations of a single field rep.

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}

Edition: Ultimate

Authorizations:AccessToken

Security scheme type: API Key

Header parameter name: pt-access-token

path parameters

organizationId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]
fieldRepId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]

Request body schema: application/json

All preferred overnight lcoations fo the field rep.

Array of PreferredOvernightLocation

id
stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
name
stringrequired[ 1 .. 250 ] characters
The name of the preferred overnight location.
location
Locationrequired
The location of the preferred overnight location. Specify address and/or geoPosition. If both are specified, the geoPosition is used as the location. If only the address is 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
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
- geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]

Responses

200 OK

Error responses (10)

400 Bad Request

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

401 Unauthorized

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

402 Payment Required

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

403 Forbidden

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

404 Not Found

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

409 Conflict

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

413 Content Too Large

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

429 Too many requests.

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

500 Internal ServerError

503 Service Unavailable

Request samples

Payload

Content typeapplication/json

[…]

{…}

"scheduleBeginAt": "2026-09-17T08:00",

"schedulePeriodDays": 7,

"skipWorkBreakToday": false,

"includeRoutePolylinesInSchedule": true,

"customerPlanningMode": "AccordingToCallIntervalsAndForcedCalls",

"trafficConditionsForFirstRide": "TypicalTraffic"

}

]

Response samples

400401402403404409413429

Content typeapplication/json

{…}

"statusCode": 400,

"message": "Invalid arguments",

"errorCode": "1011",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 401,

"message": "Access token not valid",

"errorCode": "1300",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 402,

"message": "License expired. Please contact isv-api-contact@portatour.com.",

"errorCode": "1159",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 403,

"message": "The provided access token cannot be used for the given operation or in the given context.",

"errorCode": "1304",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 404,

"message": "Resource not found",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 409,

"message": "Calculation of a schedule is currently running.",

"errorCode": "1213",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 413,

"message": "Content too large",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 429,

"message": "Too many requests",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Set scheduling constraints

PUT /1.2/organizations/{organizationId}/fieldReps/{fieldRepId}/schedulingConstraints

Replace the entire set of scheduling constraints of a single field rep. Scheduling constraints can be customer events, time blockers for scheduling, and deviating start or end times and locations of the workday. The following types are available.

Customer events:

customerEvent: Schedules a customer call at a specific date and time.
customerEventWithinTimeFrame: Schedules a customer call within the specified time frame.
customerEventAnytimeOnADay: Schedules a customer call on the specified day.

Blockers:

blocker: Blocks the scheduling of calls for the field rep during the specified date and time range.
blockerWithinTimeFrame: Schedules a blocker for the given duration within the specified date time range.
blockerAnytimeOnADay: Schedules a blocker for the given duration within the specified day.

Deviating workdays:

deviatingStartOfDay: Starts the workday at a specific location and time.
deviatingEndOfDay: Ends the workday at a specific location and time.
overnightStay: Schedules an overnight stay at a specific location for a given day.

Automatic

generic: Automatically decides what type of scheduling constraint to use.

Note: For support in different editions, see the edition notes for scheduling constraint types below.

Note: Only set the property for the type you want to create.

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}

Authorizations:AccessToken

Security scheme type: API Key

Header parameter name: pt-access-token

path parameters

organizationId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]
fieldRepId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]

Request body schema: application/json

Array of SchedulingConstraint

customerEvent
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
  stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
- subject
  stringrequired[ 1 .. 250 ] characters
- locationInformation
  CustomerEventLocationrequired
  Specifies the custom location of the customer event.
  
  locationType
  stringrequirednon-empty
  The allowed values are:
  
  "HomeLocation"
  "CustomerLocation"
  "CustomLocation"
  "Anywhere" (Edition: Ultimate)
  
  If the locationType is "HomeLocation", the home location of the field rep is used. If the locationType is "CustomerLocation", the location of the customer is used. If the locationType is "CustomLocation", the location property is used as the location. If the locationType is "Anywhere", no location is used.
  
  customLocation
  Location
  Required if locationType is "CustomLocation". Must not be set for any other value of locationType. Specifies the custom location of the customer event.
  
  address
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
- startDate
  string <yyyy-MM-dd> (IsoDateString)required
  IsoDateString is a date type that contains values in the format "yyyy-MM-dd", e.g. "2022-01-31".
- beginAt
  string <HH:mm> (IsoTimeStringMinutesPrecision)required
  IsoTimeStringMinutesPrecision is a time type that contains values in the format "HH:mm", e.g. "23:59".
- endDate
  string <yyyy-MM-dd> (IsoDateString)nullable
  If null, value of startDate is used.
  
  IsoDateString is a date type that contains values in the format "yyyy-MM-dd", e.g. "2022-01-31".
- endAt
  string <HH:mm> (IsoTimeStringMinutesPrecision)required
  IsoTimeStringMinutesPrecision is a time type that contains values in the format "HH:mm", e.g. "23:59".
- customerId
  stringrequirednon-empty^[a-zA-Z0-9-_{}]+$
  The id of the customer to which this customer event is related.
customerEventWithinTimeFrame
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.

Editions: Professional, Ultimate
- id
  stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
- subject
  stringrequired[ 1 .. 250 ] characters
- locationInformation
  CustomerEventLocationrequired
  Specifies the custom location of the customer event.
  
  locationType
  stringrequirednon-empty
  The allowed values are:
  
  "HomeLocation"
  "CustomerLocation"
  "CustomLocation"
  "Anywhere" (Edition: Ultimate)
  
  If the locationType is "HomeLocation", the home location of the field rep is used. If the locationType is "CustomerLocation", the location of the customer is used. If the locationType is "CustomLocation", the location property is used as the location. If the locationType is "Anywhere", no location is used.
  
  customLocation
  Location
  Required if locationType is "CustomLocation". Must not be set for any other value of locationType. Specifies the custom location of the customer event.
  
  address
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
- date
  string <yyyy-MM-dd> (IsoDateString)required
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)required
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)required
  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
  integer <int32>required^[1-9]\d*$
  The duration of the customer event in minutes.
  
  Note: This value must be less than the difference between earliestBeginAt and latestEndAt.
- customerId
  stringrequirednon-empty^[a-zA-Z0-9-_{}]+$
  The id of the customer to which this customer event is related.
customerEventAnytimeOnADay
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.

Editions: Professional, Ultimate
- id
  stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
- subject
  stringrequired[ 1 .. 250 ] characters
- locationInformation
  CustomerEventLocationrequired
  Specifies the custom location of the customer event.
  
  locationType
  stringrequirednon-empty
  The allowed values are:
  
  "HomeLocation"
  "CustomerLocation"
  "CustomLocation"
  "Anywhere" (Edition: Ultimate)
  
  If the locationType is "HomeLocation", the home location of the field rep is used. If the locationType is "CustomerLocation", the location of the customer is used. If the locationType is "CustomLocation", the location property is used as the location. If the locationType is "Anywhere", no location is used.
  
  customLocation
  Location
  Required if locationType is "CustomLocation". Must not be set for any other value of locationType. Specifies the custom location of the customer event.
  
  address
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
- date
  string <yyyy-MM-dd> (IsoDateString)required
  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
  integer <int32>required^[1-9]\d*$
  The duration of the customer event in minutes.
- customerId
  stringrequirednon-empty^[a-zA-Z0-9-_{}]+$
  The id of the customer to which this customer event is related.
blocker
Blocker
Blocks the scheduling of calls for the field rep during the specified date and time range. It can last for several days.

Editions: Professional, Ultimate
- id
  stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
- subject
  stringrequired[ 1 .. 250 ] characters
- locationInformation
  BlockerLocationrequired
  Specifies the location information of the blocker.
  
  locationType
  stringrequirednon-empty
  The allowed types of locations are the following strings:
  
  "HomeLocation"
  "CustomLocation"
  "Anywhere" (Edition: Ultimate)
  
  If the locationType is "CustomLocation", the location property is used as the location. If the locationType is "Anywhere", no location is used.
  
  customLocation
  Location
  Required if locationType is "CustomLocation". Must not be set for any other value of locationType. Specifies the location information of the blocker.
  
  address
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
- startDate
  string <yyyy-MM-dd> (IsoDateString)required
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)nullable
  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
  string <yyyy-MM-dd> (IsoDateString)nullable
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)nullable
  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
BlockerWithinTimeFrame
Schedules a blocker for the given duration within the specified date time range.

Editions: Professional, Ultimate
- id
  stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
- subject
  stringrequired[ 1 .. 250 ] characters
- locationInformation
  BlockerLocationrequired
  Specifies the location information of the blocker.
  
  locationType
  stringrequirednon-empty
  The allowed types of locations are the following strings:
  
  "HomeLocation"
  "CustomLocation"
  "Anywhere" (Edition: Ultimate)
  
  If the locationType is "CustomLocation", the location property is used as the location. If the locationType is "Anywhere", no location is used.
  
  customLocation
  Location
  Required if locationType is "CustomLocation". Must not be set for any other value of locationType. Specifies the location information of the blocker.
  
  address
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
- date
  string <yyyy-MM-dd> (IsoDateString)required
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)required
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)required
  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
  integer <int32>required^[1-9]\d*$
  The duration of the blocker in minutes.
  
  Note: This value must be less than the difference between earliestBeginAt and latestEndAt.
blockerAnytimeOnADay
BlockerAnytimeOnADay
Schedules a blocker for the given duration within the specified day.

Editions: Professional, Ultimate
- id
  stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
- subject
  stringrequired[ 1 .. 250 ] characters
- locationInformation
  BlockerLocationrequired
  Specifies the location information of the blocker.
  
  locationType
  stringrequirednon-empty
  The allowed types of locations are the following strings:
  
  "HomeLocation"
  "CustomLocation"
  "Anywhere" (Edition: Ultimate)
  
  If the locationType is "CustomLocation", the location property is used as the location. If the locationType is "Anywhere", no location is used.
  
  customLocation
  Location
  Required if locationType is "CustomLocation". Must not be set for any other value of locationType. Specifies the location information of the blocker.
  
  address
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
- date
  string <yyyy-MM-dd> (IsoDateString)required
  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
  integer <int32>required^[1-9]\d*$
  The duration of the blocker in minutes.
deviatingStartOfDay
DeviatingStartOfDay
Starts the workday at a specific location and time.

Editions: Professional, Ultimate
- id
  stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
- subject
  stringrequired[ 1 .. 250 ] characters
- locationInformation
  DayBoundaryLocationrequired
  Specifies the location information.
  
  locationType
  stringrequirednon-empty
  The allowed types of locations are the following strings:
  
  "HomeLocation"
  "PreferredOvernightLocation"
  "CustomLocation"
  
  If the locationType is "HomeLocation", the home location of the field rep is used. If the locationType is "PreferredOvernightLocation", the location of the preferred overnight stay is used. If the locationType is "CustomLocation", the location property is used as the location.
  
  customLocation
  Location
  Required if locationType is "CustomLocation". Must not be set for any other value of locationType. Specifies the location information.
  
  address
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
  preferredOvernightLocationId
  stringnullable
  If the locationType is "PreferredOvernightLocation" the preferredOvernightLocationId is required.
- date
  string <yyyy-MM-dd> (IsoDateString)required
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)nullable
  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".
deviatingEndOfDay
DeviatingEndOfDay
Ends the workday at a specific location and time.

Editions: Professional, Ultimate
- id
  stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
- subject
  stringrequired[ 1 .. 250 ] characters
- locationInformation
  DayBoundaryLocationrequired
  Specifies the location information.
  
  locationType
  stringrequirednon-empty
  The allowed types of locations are the following strings:
  
  "HomeLocation"
  "PreferredOvernightLocation"
  "CustomLocation"
  
  If the locationType is "HomeLocation", the home location of the field rep is used. If the locationType is "PreferredOvernightLocation", the location of the preferred overnight stay is used. If the locationType is "CustomLocation", the location property is used as the location.
  
  customLocation
  Location
  Required if locationType is "CustomLocation". Must not be set for any other value of locationType. Specifies the location information.
  
  address
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
  preferredOvernightLocationId
  stringnullable
  If the locationType is "PreferredOvernightLocation" the preferredOvernightLocationId is required.
- date
  string <yyyy-MM-dd> (IsoDateString)required
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)nullable
  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".
overnightStay
OvernightStay
Schedules an overnight stay at a specific location for a given day.

Editions: Professional, Ultimate
- id
  stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
- subject
  stringrequired[ 1 .. 250 ] characters
- locationInformation
  DayBoundaryLocationrequired
  Specifies the location information.
  
  locationType
  stringrequirednon-empty
  The allowed types of locations are the following strings:
  
  "HomeLocation"
  "PreferredOvernightLocation"
  "CustomLocation"
  
  If the locationType is "HomeLocation", the home location of the field rep is used. If the locationType is "PreferredOvernightLocation", the location of the preferred overnight stay is used. If the locationType is "CustomLocation", the location property is used as the location.
  
  customLocation
  Location
  Required if locationType is "CustomLocation". Must not be set for any other value of locationType. Specifies the location information.
  
  address
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
  preferredOvernightLocationId
  stringnullable
  If the locationType is "PreferredOvernightLocation" the preferredOvernightLocationId is required.
- startDate
  string <yyyy-MM-dd> (IsoDateString)required
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)nullable
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)nullable
  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".
generic
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
  stringrequired[ 1 .. 40 ] characters^[a-zA-Z0-9-_{}]+$
- subject
  stringrequired[ 1 .. 250 ] characters
- locationInformation
  GenericLocationrequired
  Specifies the location information of the scheduling constraint.
  
  locationType
  stringrequirednon-empty
  The allowed values are:
  
  "HomeLocation"
  "CustomerLocation"
  "CustomLocation"
  "PreferredOvernightLocation"
  "Anywhere" (Edition: Ultimate)
  
  If the locationType is "CustomLocation", the customLocation property is used as the location. If the locationType is "Anywhere", no location is used.
  
  customLocation
  Location
  Required if locationType is "CustomLocation". Must not be set for any other value of locationType. Specifies the location information of the scheduling constraint.
  
  address
  Address
  streetWithHouseNumber
  string<= 250 charactersnullable
  Contains the street and the house number of the address. Do not use if singleLineAddress is set.
  
  Example for Germany:
  
  Jahnstr. 18
  
  Example for USA:
  
  140 2nd St
  
  postalCode
  string<= 250 charactersnullable
  Contains the postal code of the address. Do not use if singleLineAddress is set.
  
  city
  string<= 250 charactersnullable
  Contains the city of the address. Do not use if singleLineAddress is set.
  
  state
  string<= 250 charactersnullable
  Contains the state of the address. Do not use if singleLineAddress is set.
  
  country
  string<= 250 charactersnullable
  Contains the country of the address. Optionally 2-letter or 3-letter ISO country codes can be used.
  
  Note: It is recommended to include the country, as omitting it may negatively impact performance and result in only the best guess being made regarding the intended country. Including the country improves both accuracy and geocoding speed.
  
  singleLineAddress
  string<= 1000 charactersnullable
  Note: This field is used for input-only and will never be returned.
  
  The singleLineAddress field represents the address as a single line. If no geoPosition is provided, the address is automatically parsed into its components. If a geoPosition is provided, the value of singleLineAddress is stored as streetWithHouseNumber in the address.
  
  You cannot use the other address properties apart from country if this property is set.
  
  geoPosition
  GeoPosition
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>required[ -90 .. 90 ]
  longitude
  number <double>required[ -180 .. 180 ]
  preferredOvernightLocationId
  stringnullable
  If the locationType is "PreferredOvernightLocation" the preferredOvernightLocationId is required.
- earliestBeginAt
  string <yyyy-MM-ddTHH:mm> (IsoDateTimeStringMinutesPrecision)required
  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
  string <yyyy-MM-ddTHH:mm> (IsoDateTimeStringMinutesPrecision)nullable
  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
  integer <int32>^[1-9]\d*$nullable
  The duration of the scheduling constraint in minutes.
  
  Note: This value must be less than the difference between earliestBeginAt and latestEndAt.
- customerId
  stringnullable
  The id of the customer to which the scheduling constraint is related.

Responses

200 OK

Error responses (10)

400 Bad Request

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

401 Unauthorized

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

402 Payment Required

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

403 Forbidden

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

404 Not Found

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

409 Conflict

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

413 Content Too Large

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

429 Too many requests.

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

500 Internal ServerError

503 Service Unavailable

Request samples

Payload

Content typeapplication/json

[…]

{…}

"customerEventAnytimeOnADay": {…}

"id": "10964307103349fea7ee17b5e99d218d",

"date": "2026-11-11",

"durationMinutes": 60,

"customerId": "16ff46b54c9047faaa35ecc78e490ae0",

"locationInformation": {…}

"locationType": "CustomerLocation"

"subject": "Williams, Derek"

}

]

Response samples

400401402403404409413429

Content typeapplication/json

{…}

"statusCode": 400,

"message": "Invalid arguments",

"errorCode": "1011",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 401,

"message": "Access token not valid",

"errorCode": "1300",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 402,

"message": "License expired. Please contact isv-api-contact@portatour.com.",

"errorCode": "1159",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 403,

"message": "The provided access token cannot be used for the given operation or in the given context.",

"errorCode": "1304",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 404,

"message": "Resource not found",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 409,

"message": "Calculation of a schedule is currently running.",

"errorCode": "1213",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 413,

"message": "Content too large",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 429,

"message": "Too many requests",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Export

The export methods are only intended to assist during development. They allow access to stored data. Read operations are throttled on purpose, and are not to be used in your production application.

List organizations

GET /1.2/export/organizations

This method requires an access token of scope:

Partner access token

Authorizations:AccessToken

Security scheme type: API Key

Header parameter name: pt-access-token

Responses

200 OK

Response schema: application/json

Array of OrganizationExport

id
string
name
string
Name of the organization.
edition
string
Determines feature and capacity limits. The following editions are available:
- "Basic"
- "Professional"
- "Ultimate"
mapRegion
string
Defines the continent used for the organization. Each organization is assigned to exactly one map region. The available map regions are:
- "Europe"
- "LatinAmerica"
- "MiddleEastAndAfrica"
- "NorthAmerica"
- "Oceania"
maxFieldRepCount
integer <int32>
Defines the maximum number of field reps for the organization.
enabledUntilUTC
string <yyyy-MM-ddTHH:mm> (IsoDateTimeStringMinutesPrecision)nullable
Determines how long the organization may be used. The value can be set to any value starting 24 hours in the past. There is no restriction on future date values.

IsoDateTimeStringMinutesPrecision is a DateTime type that contains values in the format "yyyy-MM-ddTHH:mm", e.g. "2022-01-31T23:59".

Error responses (10)

400 Bad Request

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

401 Unauthorized

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

402 Payment Required

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

403 Forbidden

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

404 Not Found

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

409 Conflict

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

413 Content Too Large

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

429 Too Many Requests

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

500 Internal ServerError

503 Service Unavailable

Response samples

200400401402403404409413429

Content typeapplication/json

[…]

{…}

"id": "{A85CCBC2-9EBD-412D-9842-12FC6D4687AE}",

"name": "Example Inc.",

"edition": "Ultimate",

"mapRegion": "Europe",

"maxFieldRepCount": 10,

"enabledUntilUTC": "2026-12-16T23:57"

}

]

Content typeapplication/json

{…}

"statusCode": 400,

"message": "Invalid arguments",

"errorCode": "1011",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 401,

"message": "Access token not valid",

"errorCode": "1300",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 402,

"message": "License expired. Please contact isv-api-contact@portatour.com.",

"errorCode": "1159",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 403,

"message": "The provided access token cannot be used for the given operation or in the given context.",

"errorCode": "1304",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 404,

"message": "Resource not found",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 409,

"message": "Calculation of a schedule is currently running.",

"errorCode": "1213",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 413,

"message": "Content too large",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 429,

"message": "Too many requests",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Get an organization

GET /1.2/export/organizations/{organizationId}

This method requires an access token with one of the following scopes:

Partner access token
Organization access token for {organizationId}

Authorizations:AccessToken

Security scheme type: API Key

Header parameter name: pt-access-token

path parameters

organizationId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]

Responses

200 OK

Response schema: application/json

id
string
name
string
Name of the organization.
edition
string
Determines feature and capacity limits. The following editions are available:
- "Basic"
- "Professional"
- "Ultimate"
mapRegion
string
Defines the continent used for the organization. Each organization is assigned to exactly one map region. The available map regions are:
- "Europe"
- "LatinAmerica"
- "MiddleEastAndAfrica"
- "NorthAmerica"
- "Oceania"
maxFieldRepCount
integer <int32>
Defines the maximum number of field reps for the organization.
enabledUntilUTC
string <yyyy-MM-ddTHH:mm> (IsoDateTimeStringMinutesPrecision)nullable
Determines how long the organization may be used. The value can be set to any value starting 24 hours in the past. There is no restriction on future date values.

IsoDateTimeStringMinutesPrecision is a DateTime type that contains values in the format "yyyy-MM-ddTHH:mm", e.g. "2022-01-31T23:59".

Error responses (10)

400 Bad Request

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

401 Unauthorized

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

402 Payment Required

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

403 Forbidden

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

404 Not Found

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

409 Conflict

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

413 Content Too Large

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

429 Too Many Requests

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

500 Internal ServerError

503 Service Unavailable

Response samples

200400401402403404409413429

Content typeapplication/json

{…}

"id": "{A85CCBC2-9EBD-412D-9842-12FC6D4687AE}",

"name": "Example Inc.",

"edition": "Ultimate",

"mapRegion": "Europe",

"maxFieldRepCount": 10,

"enabledUntilUTC": "2026-12-16T23:57"

}

Content typeapplication/json

{…}

"statusCode": 400,

"message": "Invalid arguments",

"errorCode": "1011",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 401,

"message": "Access token not valid",

"errorCode": "1300",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 402,

"message": "License expired. Please contact isv-api-contact@portatour.com.",

"errorCode": "1159",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 403,

"message": "The provided access token cannot be used for the given operation or in the given context.",

"errorCode": "1304",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 404,

"message": "Resource not found",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 409,

"message": "Calculation of a schedule is currently running.",

"errorCode": "1213",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 413,

"message": "Content too large",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 429,

"message": "Too many requests",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

List field reps

GET /1.2/export/organizations/{organizationId}/fieldReps

This method requires an access token with one of the following scopes:

Partner access token
Organization access token for {organizationId}

Authorizations:AccessToken

Security scheme type: API Key

Header parameter name: pt-access-token

path parameters

organizationId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]

Responses

200 OK

Response schema: application/json

Array of FieldRepExport

id
string
name
string
The full name of the field rep.
languageCultureName
string
Language and culture of the field rep.

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
LocationExport
The home location of the field rep.
- address
  AddressExport
  streetWithHouseNumber
  string
  Street and house number of the address.
  
  postalCode
  string
  Postal code of the address.
  
  city
  string
  City of the address.
  
  state
  stringnullable
  State of the address.
  
  country
  string
  Country of the address.
- geoPosition
  GeoPositionExport
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>[ -90 .. 90 ]
  longitude
  number <double>[ -180 .. 180 ]
  geocodeWarning
  stringnullable
  If latitude and longitude are 0, there is a description of the geocode problem. If latitude and longitude are set and there is a geocode warning, the warning is provided.
workingHours
WorkingHoursExport
Field rep's working hours per weekday.
- monday
  DailyTimeRangeExport
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
- tuesday
  DailyTimeRangeExport
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
- wednesday
  DailyTimeRangeExport
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
- thursday
  DailyTimeRangeExport
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
- friday
  DailyTimeRangeExport
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
- saturday
  DailyTimeRangeExport
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
- sunday
  DailyTimeRangeExport
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
drivingTimeFactors
DrivingTimeFactorsExport
The driving speeds that vary by road type and field rep.
- cityRoad
  number <double>[ 0.5 .. 2 ]
  This factor is applied to driving times in cities when scheduling. 0.5 = twice as fast, 1 = normal, 2 = half as fast.
- countryRoad
  number <double>[ 0.5 .. 2 ]
  This factor is applied to driving times on country roads when scheduling. 0.5 = twice as fast, 1 = normal, 2 = half as fast.
- highway
  number <double>[ 0.5 .. 2 ]
  This factor is applied to driving times on highways when scheduling. 0.5 = twice as fast, 1 = normal, 2 = half as fast.
overnightStayAwayFromHomeSettings
OvernightStayAwayFromHomeSettingsExport
Defines the conditions for overnight stays away from home.
- isAllowedOnMonday
  boolean
  Specifies whether overnight stays away from home are allowed on Mondays.
- isAllowedOnTuesday
  boolean
  Specifies whether overnight stays away from home are allowed on Tuesdays.
- isAllowedOnWednesday
  boolean
  Specifies whether overnight stays away from home are allowed on Wednesdays.
- isAllowedOnThursday
  boolean
  Specifies whether overnight stays away from home are allowed on Thursdays.
- isAllowedOnFriday
  boolean
  Specifies whether overnight stays away from home are allowed on Fridays
- isAllowedOnSaturday
  boolean
  Specifies whether overnight stays away from home are allowed on Saturdays.
- isAllowedOnSunday
  boolean
  Specifies whether overnight stays away from home are allowed on Sundays.
- minimumMetersFromHome
  integer <int32>
  Defines the minimum meters from the rep's home location. If the distance is within the minimum, no overnight stay is scheduled.
- minimumMinutesFromHome
  integer <int32>
  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.
- stayAtPreferredOvernightLocationIfWithinMinutes
  integer <int32>
  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.
generalCustomerSchedulingSettings
GeneralCustomerSchedulingSettingsExport
Applies to all of the field rep's customers for the schedule calculation.
- dueAfterLastCallIntervalPercent
  number <double>[ 0 .. 100 ]
  The value (in %) of the elapsed call interval after which the next call can be scheduled.
- adherenceToCallingHours
  string
  Specifies whether the start of the call or the entire duration of the call must be within the customer's calling hours.
  
  "StartOfCall"
  "EntireCall"
workBreak
WorkBreakExport
Specifies how to schedule a work break. If this property is null, no break is scheduled.
- scheduleWithin
  TimeRangeExport
  The time range consists of the from time and the to time.
  
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  totalMinutes
  integer <int32>nullable
  The total minutes are calculated from the specified time range.
- durationMinutes
  integer <int32>
  The duration of the work break in minutes. The duration fits within scheduleWithin.

Error responses (10)

400 Bad Request

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

401 Unauthorized

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

402 Payment Required

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

403 Forbidden

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

404 Not Found

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

409 Conflict

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

413 Content Too Large

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

429 Too Many Requests

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

500 Internal ServerError

503 Service Unavailable

Response samples

200400401402403404409413429

Content typeapplication/json

[…]

{…}

"id": "FP_01",

"name": "Alice",

"languageCultureName": "en-US",

"homeLocation": {…}

"address": {…}

"streetWithHouseNumber": "5366 College Ave",

"postalCode": "94618",

"city": "Oakland",

"state": "CA",

"country": "US"

"geoPosition": {…}

"latitude": 37.839302,

"longitude": -122.25132

}

"workingHours": {…}

"monday": {…}

"from": "08:00:00",

"to": "18:00:00"

"tuesday": {…}

"from": "08:00:00",

"to": "18:00:00"

"wednesday": {…}

"from": "08:00:00",

"to": "18:00:00"

"thursday": {…}

"from": "08:00:00",

"to": "18:00:00"

"friday": {…}

"from": "08:00:00",

"to": "18:00:00"

}

"drivingTimeFactors": {…}

"cityRoad": 1,

"countryRoad": 1,

"highway": 1

"overnightStayAwayFromHomeSettings": {…}

"isAllowedOnMonday": true,

"isAllowedOnTuesday": true,

"isAllowedOnWednesday": true,

"isAllowedOnThursday": true,

"isAllowedOnFriday": false,

"isAllowedOnSaturday": false,

"isAllowedOnSunday": false,

"minimumMetersFromHome": 0,

"minimumMinutesFromHome": 0,

"stayAtPreferredOvernightLocationIfWithinMinutes": 0

"generalCustomerSchedulingSettings": {…}

"dueAfterLastCallIntervalPercent": 70,

"adherenceToCallingHours": "StartOfCall"

"workBreak": {…}

"scheduleWithin": {…}

"from": "00:00:00",

"to": "23:59:00",

"totalMinutes": 1439

"durationMinutes": 30

}

]

Content typeapplication/json

{…}

"statusCode": 400,

"message": "Invalid arguments",

"errorCode": "1011",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 401,

"message": "Access token not valid",

"errorCode": "1300",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 402,

"message": "License expired. Please contact isv-api-contact@portatour.com.",

"errorCode": "1159",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 403,

"message": "The provided access token cannot be used for the given operation or in the given context.",

"errorCode": "1304",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 404,

"message": "Resource not found",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 409,

"message": "Calculation of a schedule is currently running.",

"errorCode": "1213",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 413,

"message": "Content too large",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 429,

"message": "Too many requests",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Get a field rep

GET /1.2/export/organizations/{organizationId}/fieldreps/{fieldRepId}

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}

Authorizations:AccessToken

Security scheme type: API Key

Header parameter name: pt-access-token

path parameters

organizationId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]
fieldRepId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]

Responses

200 OK

Response schema: application/json

id
string
name
string
The full name of the field rep.
languageCultureName
string
Language and culture of the field rep.

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
LocationExport
The home location of the field rep.
- address
  AddressExport
  streetWithHouseNumber
  string
  Street and house number of the address.
  
  postalCode
  string
  Postal code of the address.
  
  city
  string
  City of the address.
  
  state
  stringnullable
  State of the address.
  
  country
  string
  Country of the address.
- geoPosition
  GeoPositionExport
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>[ -90 .. 90 ]
  longitude
  number <double>[ -180 .. 180 ]
  geocodeWarning
  stringnullable
  If latitude and longitude are 0, there is a description of the geocode problem. If latitude and longitude are set and there is a geocode warning, the warning is provided.
workingHours
WorkingHoursExport
Field rep's working hours per weekday.
- monday
  DailyTimeRangeExport
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
- tuesday
  DailyTimeRangeExport
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
- wednesday
  DailyTimeRangeExport
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
- thursday
  DailyTimeRangeExport
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
- friday
  DailyTimeRangeExport
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
- saturday
  DailyTimeRangeExport
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
- sunday
  DailyTimeRangeExport
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
drivingTimeFactors
DrivingTimeFactorsExport
The driving speeds that vary by road type and field rep.
- cityRoad
  number <double>[ 0.5 .. 2 ]
  This factor is applied to driving times in cities when scheduling. 0.5 = twice as fast, 1 = normal, 2 = half as fast.
- countryRoad
  number <double>[ 0.5 .. 2 ]
  This factor is applied to driving times on country roads when scheduling. 0.5 = twice as fast, 1 = normal, 2 = half as fast.
- highway
  number <double>[ 0.5 .. 2 ]
  This factor is applied to driving times on highways when scheduling. 0.5 = twice as fast, 1 = normal, 2 = half as fast.
overnightStayAwayFromHomeSettings
OvernightStayAwayFromHomeSettingsExport
Defines the conditions for overnight stays away from home.
- isAllowedOnMonday
  boolean
  Specifies whether overnight stays away from home are allowed on Mondays.
- isAllowedOnTuesday
  boolean
  Specifies whether overnight stays away from home are allowed on Tuesdays.
- isAllowedOnWednesday
  boolean
  Specifies whether overnight stays away from home are allowed on Wednesdays.
- isAllowedOnThursday
  boolean
  Specifies whether overnight stays away from home are allowed on Thursdays.
- isAllowedOnFriday
  boolean
  Specifies whether overnight stays away from home are allowed on Fridays
- isAllowedOnSaturday
  boolean
  Specifies whether overnight stays away from home are allowed on Saturdays.
- isAllowedOnSunday
  boolean
  Specifies whether overnight stays away from home are allowed on Sundays.
- minimumMetersFromHome
  integer <int32>
  Defines the minimum meters from the rep's home location. If the distance is within the minimum, no overnight stay is scheduled.
- minimumMinutesFromHome
  integer <int32>
  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.
- stayAtPreferredOvernightLocationIfWithinMinutes
  integer <int32>
  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.
generalCustomerSchedulingSettings
GeneralCustomerSchedulingSettingsExport
Applies to all of the field rep's customers for the schedule calculation.
- dueAfterLastCallIntervalPercent
  number <double>[ 0 .. 100 ]
  The value (in %) of the elapsed call interval after which the next call can be scheduled.
- adherenceToCallingHours
  string
  Specifies whether the start of the call or the entire duration of the call must be within the customer's calling hours.
  
  "StartOfCall"
  "EntireCall"
workBreak
WorkBreakExport
Specifies how to schedule a work break. If this property is null, no break is scheduled.
- scheduleWithin
  TimeRangeExport
  The time range consists of the from time and the to time.
  
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  totalMinutes
  integer <int32>nullable
  The total minutes are calculated from the specified time range.
- durationMinutes
  integer <int32>
  The duration of the work break in minutes. The duration fits within scheduleWithin.

Error responses (10)

400 Bad Request

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

401 Unauthorized

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

402 Payment Required

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

403 Forbidden

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

404 Not Found

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

409 Conflict

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

413 Content Too Large

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

429 Too Many Requests

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

500 Internal ServerError

503 Service Unavailable

Response samples

200400401402403404409413429

Content typeapplication/json

{…}

"id": "FP_01",

"name": "Alice",

"languageCultureName": "en-US",

"homeLocation": {…}

"address": {…}

"streetWithHouseNumber": "5366 College Ave",

"postalCode": "94618",

"city": "Oakland",

"state": "CA",

"country": "US"

"geoPosition": {…}

"latitude": 37.839302,

"longitude": -122.25132

}

"workingHours": {…}

"monday": {…}

"from": "08:00:00",

"to": "18:00:00"

"tuesday": {…}

"from": "08:00:00",

"to": "18:00:00"

"wednesday": {…}

"from": "08:00:00",

"to": "18:00:00"

"thursday": {…}

"from": "08:00:00",

"to": "18:00:00"

"friday": {…}

"from": "08:00:00",

"to": "18:00:00"

}

"drivingTimeFactors": {…}

"cityRoad": 1,

"countryRoad": 1,

"highway": 1

"overnightStayAwayFromHomeSettings": {…}

"isAllowedOnMonday": true,

"isAllowedOnTuesday": true,

"isAllowedOnWednesday": true,

"isAllowedOnThursday": true,

"isAllowedOnFriday": false,

"isAllowedOnSaturday": false,

"isAllowedOnSunday": false,

"minimumMetersFromHome": 0,

"minimumMinutesFromHome": 0,

"stayAtPreferredOvernightLocationIfWithinMinutes": 0

"generalCustomerSchedulingSettings": {…}

"dueAfterLastCallIntervalPercent": 70,

"adherenceToCallingHours": "StartOfCall"

"workBreak": {…}

"scheduleWithin": {…}

"from": "00:00:00",

"to": "23:59:00",

"totalMinutes": 1439

"durationMinutes": 30

}

Content typeapplication/json

{…}

"statusCode": 400,

"message": "Invalid arguments",

"errorCode": "1011",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 401,

"message": "Access token not valid",

"errorCode": "1300",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 402,

"message": "License expired. Please contact isv-api-contact@portatour.com.",

"errorCode": "1159",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 403,

"message": "The provided access token cannot be used for the given operation or in the given context.",

"errorCode": "1304",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 404,

"message": "Resource not found",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 409,

"message": "Calculation of a schedule is currently running.",

"errorCode": "1213",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 413,

"message": "Content too large",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 429,

"message": "Too many requests",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

List customers

GET /1.2/export/organizations/{organizationId}/fieldreps/{fieldRepId}/customers

This method requires an access token with one of the following scopes:

Partner access token
Organization access token for {organizationId}

Authorizations:AccessToken

Security scheme type: API Key

Header parameter name: pt-access-token

path parameters

organizationId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]
fieldRepId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]

Responses

200 OK

Response schema: application/json

Array of CustomerExport

id
string
name
string
The name of the customer.
location
LocationExport
The customer's location.
- address
  AddressExport
  streetWithHouseNumber
  string
  Street and house number of the address.
  
  postalCode
  string
  Postal code of the address.
  
  city
  string
  City of the address.
  
  state
  stringnullable
  State of the address.
  
  country
  string
  Country of the address.
- geoPosition
  GeoPositionExport
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>[ -90 .. 90 ]
  longitude
  number <double>[ -180 .. 180 ]
  geocodeWarning
  stringnullable
  If latitude and longitude are 0, there is a description of the geocode problem. If latitude and longitude are set and there is a geocode warning, the warning is provided.
activatedOn
string <yyyy-MM-dd> (IsoDateString)
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
string <yyyy-MM-dd> (IsoDateString)nullable
Date of the last call.

IsoDateString is a date type that contains values in the format "yyyy-MM-dd", e.g. "2022-01-31".
lastMissedCallOn
string <yyyy-MM-dd> (IsoDateString)nullable
Prevents the customer from being rescheduled for a schedule calculation on the same day.

IsoDateString is a date type that contains values in the format "yyyy-MM-dd", e.g. "2022-01-31".
callInterval
CallIntervalExport
The interval at which the customer has to be called.
- days
  integer <int32>
  The customer's call interval in days. A next call can be scheduled when the dueAfterLastCallIntervalPercent since the last call is reached.
- isAdherencePreferred
  boolean
  If set to 'true', helps avoid exceeding the customer's call interval - even if the field rep's territory is too large.
callDurationMinutes
integer <int32>
The duration of a call in minutes.
schedulingRestriction
stringnullable
Specifies whether to schedule the customer only in certain calendar weeks.

The allowed values are:
- "OnlyInOddWeeks"
- "OnlyInEvenWeeks"
- "OnlyInFirstOfThreeWeeks"
- "OnlyInSecondOfThreeWeeks"
- "OnlyInThirdOfThreeWeeks"
- "OnlyInFirstOfFourWeeks"
- "OnlyInSecondOfFourWeeks"
- "OnlyInThirdOfFourWeeks"
- "OnlyInFourthOfFourWeeks"
doForceCall
boolean
If true, this customer will be included in the next schedule regardless of their last call date and call interval.
callingHours
CallingHoursExport
Defines the hours per weekday that a customer can be called. Per day there can be up to 2 periods of possible calls. The periods on one day do not overlap. A preferred period will be preferably choosen for scheduling.
- mondayPeriod1
  DailyCallingHoursExport
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  isPreferred
  boolean
- mondayPeriod2
  DailyCallingHoursExport
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  isPreferred
  boolean
- tuesdayPeriod1
  DailyCallingHoursExport
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  isPreferred
  boolean
- tuesdayPeriod2
  DailyCallingHoursExport
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  isPreferred
  boolean
- wednesdayPeriod1
  DailyCallingHoursExport
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  isPreferred
  boolean
- wednesdayPeriod2
  DailyCallingHoursExport
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  isPreferred
  boolean
- thursdayPeriod1
  DailyCallingHoursExport
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  isPreferred
  boolean
- thursdayPeriod2
  DailyCallingHoursExport
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  isPreferred
  boolean
- fridayPeriod1
  DailyCallingHoursExport
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  isPreferred
  boolean
- fridayPeriod2
  DailyCallingHoursExport
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  isPreferred
  boolean
- saturdayPeriod1
  DailyCallingHoursExport
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  isPreferred
  boolean
- saturdayPeriod2
  DailyCallingHoursExport
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  isPreferred
  boolean
- sundayPeriod1
  DailyCallingHoursExport
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  isPreferred
  boolean
- sundayPeriod2
  DailyCallingHoursExport
  from
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  to
  string <HH:mm:ss> (IsoTimeStringSecondsPrecision)
  IsoTimeStringSecondsPrecision is a time type that contains values in the format "HH:mm:ss", e.g. "23:59:59".
  
  isPreferred
  boolean
callBlocks
array of CallBlockExportnullable
Used to block calls from being scheduled for the customer on the specified days, e.g. the customer's holidays.
- beginOn
  string <yyyy-MM-dd> (IsoDateString)
  IsoDateString is a date type that contains values in the format "yyyy-MM-dd", e.g. "2022-01-31".
- endOn
  string <yyyy-MM-dd> (IsoDateString)
  IsoDateString is a date type that contains values in the format "yyyy-MM-dd", e.g. "2022-01-31".
- description
  string<= 250 charactersnullable

Error responses (10)

400 Bad Request

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

401 Unauthorized

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

402 Payment Required

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

403 Forbidden

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

404 Not Found

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

409 Conflict

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

413 Content Too Large

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

429 Too Many Requests

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

500 Internal ServerError

503 Service Unavailable

Response samples

200400401402403404409413429

Content typeapplication/json

[…]

{…}

"id": "16ff46b54c9047faaa35ecc78e490ae0",

"name": "Williams, Derek",

"location": {…}

"address": {…}

"streetWithHouseNumber": "140 2nd St",

"postalCode": "94971",

"city": "Tomales",

"state": "California",

"country": "USA"

"geoPosition": {…}

"latitude": 38.248,

"longitude": -122.9055

}

"activatedOn": "2021-10-24",

"lastCallOn": "2022-11-13",

"callInterval": {…}

"days": 30

"callDurationMinutes": 15,

"callingHours": {…}

"tuesdayPeriod1": {…}

"from": "07:00:00",

"to": "12:00:00"

"wednesdayPeriod1": {…}

"from": "07:00:00",

"to": "12:00:00"

"thursdayPeriod1": {…}

"from": "07:00:00",

"to": "12:00:00"

}

"callBlocks": […]

{…}

"beginOn": "2026-09-17",

"endOn": "2026-10-01",

"description": "Holiday"

}

]

}

]

Content typeapplication/json

{…}

"statusCode": 400,

"message": "Invalid arguments",

"errorCode": "1011",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 401,

"message": "Access token not valid",

"errorCode": "1300",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 402,

"message": "License expired. Please contact isv-api-contact@portatour.com.",

"errorCode": "1159",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 403,

"message": "The provided access token cannot be used for the given operation or in the given context.",

"errorCode": "1304",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 404,

"message": "Resource not found",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 409,

"message": "Calculation of a schedule is currently running.",

"errorCode": "1213",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 413,

"message": "Content too large",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 429,

"message": "Too many requests",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

List scheduling constraints

GET /1.2/export/organizations/{organizationId}/fieldreps/{fieldRepId}/schedulingConstraints

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}

Authorizations:AccessToken

Security scheme type: API Key

Header parameter name: pt-access-token

path parameters

organizationId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]
fieldRepId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]

Responses

200 OK

Response schema: application/json

Array of SchedulingConstraintExport

type
string
The type identicates which of the the properties is set. You do not have to check all properties for null values, but only access the one mentioned in the type field. For example, the field type has the value "CustomerEvent" then you can instantly access the property customerEvent without null check of the other properties. It is ensured that only the property named in the type field is set.
customerEvent
CustomerEventExport
Schedules a customer call at the specified date and time for the given duration. The event can last for several days.
- id
  string
- subject
  string
- locationInformation
  CustomerEventLocationExport
  Specifies the custom location information of the customer event.
  
  locationType
  string
  The allowed values are:
  
  "HomeLocation"
  "CustomerLocation"
  "CustomLocation"
  "Anywhere"
  
  If the locationType is "CustomLocation", the location property is used as the location. If the locationType is "Anywhere", no location is used.
  
  location
  LocationExport
  Specifies the location. The geoPosition is used as the location.
  
  address
  AddressExport
  streetWithHouseNumber
  string
  Street and house number of the address.
  
  postalCode
  string
  Postal code of the address.
  
  city
  string
  City of the address.
  
  state
  stringnullable
  State of the address.
  
  country
  string
  Country of the address.
  
  geoPosition
  GeoPositionExport
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>[ -90 .. 90 ]
  longitude
  number <double>[ -180 .. 180 ]
  geocodeWarning
  stringnullable
  If latitude and longitude are 0, there is a description of the geocode problem. If latitude and longitude are set and there is a geocode warning, the warning is provided.
- startDate
  string <yyyy-MM-dd> (IsoDateString)
  IsoDateString is a date type that contains values in the format "yyyy-MM-dd", e.g. "2022-01-31".
- beginAt
  string <HH:mm> (IsoTimeStringMinutesPrecision)
  IsoTimeStringMinutesPrecision is a time type that contains values in the format "HH:mm", e.g. "23:59".
- endDate
  string <yyyy-MM-dd> (IsoDateString)
  If null, value of startDate is used.
  
  IsoDateString is a date type that contains values in the format "yyyy-MM-dd", e.g. "2022-01-31".
- endAt
  string <HH:mm> (IsoTimeStringMinutesPrecision)
  IsoTimeStringMinutesPrecision is a time type that contains values in the format "HH:mm", e.g. "23:59".
- customerId
  string
  The id of the customer to which this customer event is related.
customerEventWithinTimeFrame
CustomerEventWithinTimeFrameExport
Schedules a customer call within the specified time frame.
- id
  string
- subject
  string
- locationInformation
  CustomerEventLocationExport
  Specifies the custom location information of the customer event.
  
  locationType
  string
  The allowed values are:
  
  "HomeLocation"
  "CustomerLocation"
  "CustomLocation"
  "Anywhere"
  
  If the locationType is "CustomLocation", the location property is used as the location. If the locationType is "Anywhere", no location is used.
  
  location
  LocationExport
  Specifies the location. The geoPosition is used as the location.
  
  address
  AddressExport
  streetWithHouseNumber
  string
  Street and house number of the address.
  
  postalCode
  string
  Postal code of the address.
  
  city
  string
  City of the address.
  
  state
  stringnullable
  State of the address.
  
  country
  string
  Country of the address.
  
  geoPosition
  GeoPositionExport
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>[ -90 .. 90 ]
  longitude
  number <double>[ -180 .. 180 ]
  geocodeWarning
  stringnullable
  If latitude and longitude are 0, there is a description of the geocode problem. If latitude and longitude are set and there is a geocode warning, the warning is provided.
- date
  string <yyyy-MM-dd> (IsoDateString)
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)
  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
  integer <int32>
  The duration of the customer event in minutes.
- customerId
  string
  The id of the customer to which this customer event is related.
customerEventAnytimeOnADay
CustomerEventAnytimeOnADayExport
Schedules a customer call within the specified time frame.
- id
  string
- subject
  string
- locationInformation
  CustomerEventLocationExport
  Specifies the custom location information of the customer event.
  
  locationType
  string
  The allowed values are:
  
  "HomeLocation"
  "CustomerLocation"
  "CustomLocation"
  "Anywhere"
  
  If the locationType is "CustomLocation", the location property is used as the location. If the locationType is "Anywhere", no location is used.
  
  location
  LocationExport
  Specifies the location. The geoPosition is used as the location.
  
  address
  AddressExport
  streetWithHouseNumber
  string
  Street and house number of the address.
  
  postalCode
  string
  Postal code of the address.
  
  city
  string
  City of the address.
  
  state
  stringnullable
  State of the address.
  
  country
  string
  Country of the address.
  
  geoPosition
  GeoPositionExport
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>[ -90 .. 90 ]
  longitude
  number <double>[ -180 .. 180 ]
  geocodeWarning
  stringnullable
  If latitude and longitude are 0, there is a description of the geocode problem. If latitude and longitude are set and there is a geocode warning, the warning is provided.
- date
  string <yyyy-MM-dd> (IsoDateString)
  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
  integer <int32>
  The duration of the customer event in minutes.
- customerId
  string
  The id of the customer to which this customer event is related.
blocker
BlockerExport
Blocks the scheduling of calls for the field rep during the specified date and time range. It can last for several days.
- id
  string
- subject
  string
- locationInformation
  BlockerLocationExport
  The custom location information of the blocker.
  
  locationType
  string
  The possible types of locations are the following strings:
  
  "HomeLocation"
  "CustomLocation"
  "Anywhere"
  
  If the locationType is "CustomLocation", the location property is used as the location. If the locationType is "Anywhere", no location is used.
  
  location
  LocationExport
  Specifies the location. The geoPosition is used as the location.
  
  address
  AddressExport
  streetWithHouseNumber
  string
  Street and house number of the address.
  
  postalCode
  string
  Postal code of the address.
  
  city
  string
  City of the address.
  
  state
  stringnullable
  State of the address.
  
  country
  string
  Country of the address.
  
  geoPosition
  GeoPositionExport
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>[ -90 .. 90 ]
  longitude
  number <double>[ -180 .. 180 ]
  geocodeWarning
  stringnullable
  If latitude and longitude are 0, there is a description of the geocode problem. If latitude and longitude are set and there is a geocode warning, the warning is provided.
- startDate
  string <yyyy-MM-dd> (IsoDateString)
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)
  The start time of the blocker.
  
  IsoTimeStringMinutesPrecision is a time type that contains values in the format "HH:mm", e.g. "23:59".
- endDate
  string <yyyy-MM-dd> (IsoDateString)
  The end date of the blocker. 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
  string <HH:mm> (IsoTimeStringMinutesPrecision)
  The end time of the blocker.
  
  IsoTimeStringMinutesPrecision is a time type that contains values in the format "HH:mm", e.g. "23:59".
blockerWithinTimeFrame
BlockerWithinTimeFrameExport
Schedules a blocker for the given duration within the specified date time range.
- id
  string
- subject
  string
- locationInformation
  BlockerLocationExport
  The custom location information of the blocker.
  
  locationType
  string
  The possible types of locations are the following strings:
  
  "HomeLocation"
  "CustomLocation"
  "Anywhere"
  
  If the locationType is "CustomLocation", the location property is used as the location. If the locationType is "Anywhere", no location is used.
  
  location
  LocationExport
  Specifies the location. The geoPosition is used as the location.
  
  address
  AddressExport
  streetWithHouseNumber
  string
  Street and house number of the address.
  
  postalCode
  string
  Postal code of the address.
  
  city
  string
  City of the address.
  
  state
  stringnullable
  State of the address.
  
  country
  string
  Country of the address.
  
  geoPosition
  GeoPositionExport
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>[ -90 .. 90 ]
  longitude
  number <double>[ -180 .. 180 ]
  geocodeWarning
  stringnullable
  If latitude and longitude are 0, there is a description of the geocode problem. If latitude and longitude are set and there is a geocode warning, the warning is provided.
- date
  string <yyyy-MM-dd> (IsoDateString)
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)nullable
  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
  integer <int32>
  The duration of the blocker in minutes.
  
  Note: This value must be less than the difference between earliestBeginAt and latestEndAt.
blockerAnytimeOnADay
BlockerAnytimeOnADayExport
Schedules a blocker for the given duration within the specified day.
- id
  string
- subject
  string
- locationInformation
  BlockerLocationExport
  The custom location information of the blocker.
  
  locationType
  string
  The possible types of locations are the following strings:
  
  "HomeLocation"
  "CustomLocation"
  "Anywhere"
  
  If the locationType is "CustomLocation", the location property is used as the location. If the locationType is "Anywhere", no location is used.
  
  location
  LocationExport
  Specifies the location. The geoPosition is used as the location.
  
  address
  AddressExport
  streetWithHouseNumber
  string
  Street and house number of the address.
  
  postalCode
  string
  Postal code of the address.
  
  city
  string
  City of the address.
  
  state
  stringnullable
  State of the address.
  
  country
  string
  Country of the address.
  
  geoPosition
  GeoPositionExport
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>[ -90 .. 90 ]
  longitude
  number <double>[ -180 .. 180 ]
  geocodeWarning
  stringnullable
  If latitude and longitude are 0, there is a description of the geocode problem. If latitude and longitude are set and there is a geocode warning, the warning is provided.
- date
  string <yyyy-MM-dd> (IsoDateString)
  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
  integer <int32>
  The duration of the blocker in minutes.
deviatingStartOfDay
DeviatingStartOfDayExport
Starts the workday at a specific location and time.
- id
  string
- subject
  string
- locationInformation
  DayBoundaryLocationExport
  Specifies the custom location information.
  
  locationType
  string
  The allowed types of locations are the following strings:
  
  "HomeLocation"
  "PreferredOvernightLocation"
  "CustomLocation"
  
  If the locationType is "CustomLocation", the location property is used as the location.
  
  location
  LocationExport
  Specifies the location. The geoPosition is used as the location.
  
  address
  AddressExport
  streetWithHouseNumber
  string
  Street and house number of the address.
  
  postalCode
  string
  Postal code of the address.
  
  city
  string
  City of the address.
  
  state
  stringnullable
  State of the address.
  
  country
  string
  Country of the address.
  
  geoPosition
  GeoPositionExport
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>[ -90 .. 90 ]
  longitude
  number <double>[ -180 .. 180 ]
  geocodeWarning
  stringnullable
  If latitude and longitude are 0, there is a description of the geocode problem. If latitude and longitude are set and there is a geocode warning, the warning is provided.
  
  preferredOvernightLocationId
  stringnullable
- date
  string <yyyy-MM-dd> (IsoDateString)
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)
  The start time of the deviating start of day.
  
  IsoTimeStringMinutesPrecision is a time type that contains values in the format "HH:mm", e.g. "23:59".
deviatingEndOfDay
DeviatingEndOfDayExport
Ends the workday at a specific location and time.
- id
  string
- subject
  string
- locationInformation
  DayBoundaryLocationExport
  Specifies the custom location information.
  
  locationType
  string
  The allowed types of locations are the following strings:
  
  "HomeLocation"
  "PreferredOvernightLocation"
  "CustomLocation"
  
  If the locationType is "CustomLocation", the location property is used as the location.
  
  location
  LocationExport
  Specifies the location. The geoPosition is used as the location.
  
  address
  AddressExport
  streetWithHouseNumber
  string
  Street and house number of the address.
  
  postalCode
  string
  Postal code of the address.
  
  city
  string
  City of the address.
  
  state
  stringnullable
  State of the address.
  
  country
  string
  Country of the address.
  
  geoPosition
  GeoPositionExport
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>[ -90 .. 90 ]
  longitude
  number <double>[ -180 .. 180 ]
  geocodeWarning
  stringnullable
  If latitude and longitude are 0, there is a description of the geocode problem. If latitude and longitude are set and there is a geocode warning, the warning is provided.
  
  preferredOvernightLocationId
  stringnullable
- date
  string <yyyy-MM-dd> (IsoDateString)
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)nullable
  The end time of the deviating end of day.
  
  IsoTimeStringMinutesPrecision is a time type that contains values in the format "HH:mm", e.g. "23:59".
overnightStay
OvernightStayExport
Schedules an overnight stay at a specific location for a given day.
- id
  string
- subject
  string
- locationInformation
  DayBoundaryLocationExport
  Specifies the custom location information.
  
  locationType
  string
  The allowed types of locations are the following strings:
  
  "HomeLocation"
  "PreferredOvernightLocation"
  "CustomLocation"
  
  If the locationType is "CustomLocation", the location property is used as the location.
  
  location
  LocationExport
  Specifies the location. The geoPosition is used as the location.
  
  address
  AddressExport
  streetWithHouseNumber
  string
  Street and house number of the address.
  
  postalCode
  string
  Postal code of the address.
  
  city
  string
  City of the address.
  
  state
  stringnullable
  State of the address.
  
  country
  string
  Country of the address.
  
  geoPosition
  GeoPositionExport
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>[ -90 .. 90 ]
  longitude
  number <double>[ -180 .. 180 ]
  geocodeWarning
  stringnullable
  If latitude and longitude are 0, there is a description of the geocode problem. If latitude and longitude are set and there is a geocode warning, the warning is provided.
  
  preferredOvernightLocationId
  stringnullable
- startDate
  string <yyyy-MM-dd> (IsoDateString)
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)
  The time at which the overnight stay begins.
  
  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
  string <HH:mm> (IsoTimeStringMinutesPrecision)
  The time at which the overnight stay ends on the next day.
  
  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".
generic
GenericExport
If the requirements for a particular type are not met, the scheduling constraint cannot be converted. It is generic and cannot be scheduled.
- id
  string
- subject
  string
- locationInformation
  GenericLocationExport
  Specifies the custom location information of the scheduling constraint.
  
  locationType
  string
  The allowed values are:
  
  "HomeLocation"
  "CustomerLocation"
  "CustomLocation"
  "PreferredOvernightLocation"
  "Anywhere"
  
  If the locationType is "CustomLocation", the location property is used as the location. If the locationType is "Anywhere", no location is used.
  
  location
  LocationExport
  Specifies the location. The geoPosition is used as the location.
  
  address
  AddressExport
  streetWithHouseNumber
  string
  Street and house number of the address.
  
  postalCode
  string
  Postal code of the address.
  
  city
  string
  City of the address.
  
  state
  stringnullable
  State of the address.
  
  country
  string
  Country of the address.
  
  geoPosition
  GeoPositionExport
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>[ -90 .. 90 ]
  longitude
  number <double>[ -180 .. 180 ]
  geocodeWarning
  stringnullable
  If latitude and longitude are 0, there is a description of the geocode problem. If latitude and longitude are set and there is a geocode warning, the warning is provided.
  
  preferredOvernightLocationId
  stringnullable
  The id of the preferred overnight location if the locationType is "PreferredOvernightLocation". It must not be set for other locationTypes.
- earliestBeginAt
  string <yyyy-MM-ddTHH:mm> (IsoDateTimeStringMinutesPrecision)
  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
  string <yyyy-MM-ddTHH:mm> (IsoDateTimeStringMinutesPrecision)nullable
  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
  integer <int32>nullable
  The duration of the scheduling constraint in minutes.
- customerId
  stringnullable
  The id of the customer to which the scheduling constraint is related.

Error responses (10)

400 Bad Request

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

401 Unauthorized

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

402 Payment Required

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

403 Forbidden

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

404 Not Found

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

409 Conflict

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

413 Content Too Large

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

429 Too Many Requests

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

500 Internal ServerError

503 Service Unavailable

Response samples

200400401402403404409413429

Content typeapplication/json

[…]

{…}

"customerEventAnytimeOnADay": {…}

"id": "10964307103349fea7ee17b5e99d218d",

"date": "2026-11-11",

"durationMinutes": 60,

"customerId": "16ff46b54c9047faaa35ecc78e490ae0",

"locationInformation": {…}

"locationType": "CustomerLocation"

"subject": "Williams, Derek"

}

]

Content typeapplication/json

{…}

"statusCode": 400,

"message": "Invalid arguments",

"errorCode": "1011",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 401,

"message": "Access token not valid",

"errorCode": "1300",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 402,

"message": "License expired. Please contact isv-api-contact@portatour.com.",

"errorCode": "1159",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 403,

"message": "The provided access token cannot be used for the given operation or in the given context.",

"errorCode": "1304",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 404,

"message": "Resource not found",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 409,

"message": "Calculation of a schedule is currently running.",

"errorCode": "1213",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 413,

"message": "Content too large",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 429,

"message": "Too many requests",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

List preferred overnight locations

GET /1.2/export/organizations/{organizationId}/fieldreps/{fieldRepId}/preferredOvernightLocations

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}

Authorizations:AccessToken

Security scheme type: API Key

Header parameter name: pt-access-token

path parameters

organizationId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]
fieldRepId
stringrequired<= 40 characters^[a-zA-Z0-9-_{}]+$
An id must consist of the following characters: [a-zA-Z0-9-_{}]

Responses

200 OK

Response schema: application/json

Array of PreferredOvernightLocationExport

id
string
name
string<= 250 characters
The name of the preferred overnight location.
location
LocationExport
The location of the preferred overnight location.
- address
  AddressExport
  streetWithHouseNumber
  string
  Street and house number of the address.
  
  postalCode
  string
  Postal code of the address.
  
  city
  string
  City of the address.
  
  state
  stringnullable
  State of the address.
  
  country
  string
  Country of the address.
- geoPosition
  GeoPositionExport
  WGS84 (EPSG:4326) coordinates of the geoposition.
  
  latitude
  number <double>[ -90 .. 90 ]
  longitude
  number <double>[ -180 .. 180 ]
  geocodeWarning
  stringnullable
  If latitude and longitude are 0, there is a description of the geocode problem. If latitude and longitude are set and there is a geocode warning, the warning is provided.

Error responses (10)

400 Bad Request

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

401 Unauthorized

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

402 Payment Required

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

403 Forbidden

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

404 Not Found

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

409 Conflict

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

413 Content Too Large

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

429 Too Many Requests

Response schema: application/json

statusCode
integer <int32>
Corresponds to the HTTP status code.
message
string<= 1000 characters
Describes the error.
errorCode
stringnullable
correlationId
string
Is used to identify related internal methods involved in the request.

500 Internal ServerError

503 Service Unavailable

Response samples

200400401402403404409413429

Content typeapplication/json

[…]

{…}

"scheduleBeginAt": "2026-09-17T08:00",

"schedulePeriodDays": 7,

"skipWorkBreakToday": false,

"includeRoutePolylinesInSchedule": true,

"customerPlanningMode": "AccordingToCallIntervalsAndForcedCalls",

"trafficConditionsForFirstRide": "TypicalTraffic"

}

]

Content typeapplication/json

{…}

"statusCode": 400,

"message": "Invalid arguments",

"errorCode": "1011",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 401,

"message": "Access token not valid",

"errorCode": "1300",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 402,

"message": "License expired. Please contact isv-api-contact@portatour.com.",

"errorCode": "1159",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 403,

"message": "The provided access token cannot be used for the given operation or in the given context.",

"errorCode": "1304",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 404,

"message": "Resource not found",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 409,

"message": "Calculation of a schedule is currently running.",

"errorCode": "1213",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 413,

"message": "Content too large",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Content typeapplication/json

{…}

"statusCode": 429,

"message": "Too many requests",

"correlationId": "RID-ZF4aNc4KacM4pAdqWNJQiwAAA-Q"

}

Error Codes

Here you can find a list of all possible error codes that may occur when using the API. The following terms can be used interchangeably:

Term in message	Term in documentation
user	field rep
appointment	scheduling constraint
account	organization

Schedule

ErrorCode	ErrorMessage	HTTP Status
1002	The schedule cannot be calculated with your current settings. Change one of the following settings and try again: Ensure your working hours allow for at least one free day; ensure your overnight stay settings allow for at least one night at your home location; shorten the planning period in the scheduling parameters to 6 days or fewer.	400 Bad Request
1003	The parameters provided do not result in at least one scheduled day.	400 Bad Request
1026	The total amount of different addresses of customers with call intervals or reservations and scheduling constraints exceeds the technical limit. Contact isv-api-contact@portatour.com.	400 Bad Request
1033	The destination cannot be reached.	400 Bad Request
1035	The number of supported scheduling constraints has been exceeded and thus the action cannot be completed.	400 Bad Request
1036	The number of supported call blocks per field rep has been exceeded and thus the action cannot be completed.	400 Bad Request
1038	The number of supported customers has been exceeded and thus the action cannot be completed.	400 Bad Request
1039	The number of supported customers with call interval per field rep has been exceeded and thus the action cannot be completed.	400 Bad Request
1041	The number of supported preferred overnight locations has been exceeded and thus the action cannot be completed.	400 Bad Request
1042	The number of supported reservations has been exceeded and thus the action cannot be completed.	400 Bad Request
1046	The number of supported customers with call intervals or reservations has been exceeded and thus the schedule calculation has been aborted.	400 Bad Request
1047	Home address not geocoded. This error code can only occur if field reps were uploaded using API version 1.0.	400 Bad Request
1051	No more calculations are allowed today, since you already consumed too many minutes of server computation time.	400 Bad Request
1052	The calculation was canceled because the resulting schedule would contain too many customer calls per day. Tip: Extend the customer call durations to reduce the number of calls.	400 Bad Request
1053	The calculation was canceled because the resulting schedule would contain too many customer calls. Tip: Shorten the planning period in the scheduling parameters or extend the call durations.	400 Bad Request
1054	The calculation was canceled because the resulting schedule would contain too many customer calls per week. Tip: Shorten the planning period in the scheduling parameters to 6 days or fewer. Alternatively, extend the call durations to reduce the number of calls.	400 Bad Request
1055	The calculation has been canceled because the resulting schedule would contain more than 125 customer calls. Tip: Shorten the planning period in the schedule parameters or extend the call durations.	400 Bad Request
1056	The calculation has been canceled because the planning period is longer than the call interval of at least one customer. Tip: Shorten the planning period in days in the scheduling parameters.	400 Bad Request
1057	Geocoding of home address failed.	400 Bad Request
1058	Geocoding of home address failed, unknown country.	400 Bad Request
1059	Geocoding of home address failed. Country is not included in the licensed map material.	400 Bad Request
1100	The planning period was shortened because portatour® can only optimize a maximum of 125 customer calls per week. To schedule for a longer period during one calculation, extend customers' call durations or shorten your working hours. Change the planning period accordingly in the scheduling parameters of the schedule.	400 Bad Request
1130	Calculation of routes failed	400 Bad Request
1131	Routes could not be calculated. Please try again later.	400 Bad Request
1133	Invalid access token.	401 Unauthorized
1156	Your organization has been blocked. Contact isv-api-contact@portatour.com.	400 Bad Request
1159	License expired. Please contact isv-api-contact@portatour.com.	402 Payment Required
1161	The field rep has been blocked. Contact isv-api-contact@portatour.com.	400 Bad Request
1212	No schedule available.	400 Bad Request
1213	Calculation of a schedule is currently running.	409 Conflict
1214	The schedule is outdated.	400 Bad Request
1300	Access token not valid	401 Unauthorized
1304	The provided access token cannot be used for the given operation or in the given context.	403 Forbidden
1309	The specified organization does not exist, is not enabled or is not accessible.	404 Not Found
1310	The specified field rep does not exist, is deleted or not accessible.	404 Not Found
2000	Feature not included in your edition or limit exceeded. For details, see the corresponding error message.	400 Bad Request

AccessTokens

ErrorCode	ErrorMessage	HTTP Status
1133	Invalid access token.	401 Unauthorized
1156	Your organization has been blocked. Contact isv-api-contact@portatour.com.	400 Bad Request
1159	License expired. Please contact isv-api-contact@portatour.com.	402 Payment Required
1161	The field rep has been blocked. Contact isv-api-contact@portatour.com.	400 Bad Request
1300	Access token not valid	401 Unauthorized
1304	The provided access token cannot be used for the given operation or in the given context.	403 Forbidden
1309	The specified organization does not exist, is not enabled or is not accessible.	404 Not Found
1310	The specified field rep does not exist, is deleted or not accessible.	404 Not Found
1314	The specified target access token does not exist, is revoked, expired or not accessible.	400 Bad Request
1319	The rate limit for the creation of access tokens for the specified scope (Partner) has been reached. A maximum of %d new access tokens are allowed within %d hours. The rate limit for the creation of access tokens for the specified scope (Organization with organizationId organizationId) has been reached. A maximum of %d new access tokens are allowed within %d hours. The rate limit for the creation of access tokens for the specified scope (FieldRep with fieldRepId fieldRepId) has been reached. A maximum of %d new access tokens are allowed within %d hours.	429 Too Many Requests

Organizations

ErrorCode	ErrorMessage	HTTP Status
1006	Parallel operations for organizations within the same partner are not permitted.	400 Bad Request
1133	Invalid access token.	401 Unauthorized
1156	Your organization has been blocked. Contact isv-api-contact@portatour.com.	400 Bad Request
1159	License expired. Please contact isv-api-contact@portatour.com.	402 Payment Required
1161	The field rep has been blocked. Contact isv-api-contact@portatour.com.	400 Bad Request
1300	Access token not valid	401 Unauthorized
1304	The provided access token cannot be used for the given operation or in the given context.	403 Forbidden
1309	The specified organization does not exist, is not enabled or is not accessible.	404 Not Found
1310	The specified field rep does not exist, is deleted or not accessible.	404 Not Found
1311	An organization with the provided organizationId already exists.	400 Bad Request
1315	Maximum count of organizations exceeded.	400 Bad Request
1318	The date and time specified for enabledUntilUTC is invalid.	400 Bad Request
2000	Feature not included in your edition or limit exceeded. For details, see the corresponding error message.	400 Bad Request

FieldReps

ErrorCode	ErrorMessage	HTTP Status
1057	Geocoding of home address failed.	400 Bad Request
1058	Geocoding of home address failed, unknown country.	400 Bad Request
1059	Geocoding of home address failed. Country is not included in the licensed map material.	400 Bad Request
1133	Invalid access token.	401 Unauthorized
1156	Your organization has been blocked. Contact isv-api-contact@portatour.com.	400 Bad Request
1157	Maximum count of active field reps exceeded.	400 Bad Request
1159	License expired. Please contact isv-api-contact@portatour.com.	402 Payment Required
1161	The field rep has been blocked. Contact isv-api-contact@portatour.com.	400 Bad Request
1188	Customer address not geocoded.	400 Bad Request
1189	Home address not geocoded. This error code can only occur if field reps were uploaded using API version 1.0.	400 Bad Request
1190	Invalid customer ID	400 Bad Request
1300	Access token not valid	401 Unauthorized
1304	The provided access token cannot be used for the given operation or in the given context.	403 Forbidden
1309	The specified organization does not exist, is not enabled or is not accessible.	404 Not Found
1310	The specified field rep does not exist, is deleted or not accessible.	404 Not Found
1313	A field rep with the provided id already exists.	400 Bad Request
1316	Maximum count of total field reps exceeded.	400 Bad Request
1317	Maximum count of undeleted field reps exceeded.	400 Bad Request
2000	Feature not included in your edition or limit exceeded. For details, see the corresponding error message.	400 Bad Request

Schedule Messages

The following table shows the terms that are used in schedule messages instead of the terms that are generally used in this documentation. These messages are intended to be shown directly to end users and therefore are translated to the language of the field rep automatically.

Term in message	Term in documentation
user	field rep
appointment	scheduling constraint
reservation	customer with flag `doForceCall` is true
business hours	calling hours

MessageId	Description
5001	There are %d addresses without geoposition.
5002	All customers have activation dates in the future.
5003	Appointment "%s" has been postponed to %s to be reachable in time.
5004	Your home location is positioned such that all customers are too far away to be reachable within a scheduled day.
5005	Current traffic is currently not available.
5006	Current traffic for the first drive was not available.
5007	%d customers are further away from your home location than %d %s (beeline). Tip: In general, to speed up schedule calculations, deactivate or delete customers that are very far afield and whom you do not actually visit. You can use the map view for this purpose.
5012	There are no business hours configured for your customers.
5013	Planning mode is set to 'reservations and appointments only'. However, you have not created any reservations nor scheduled any appointments for the upcoming days.
5014	There are %d customers with 'last call' date in the future: %s
5016	The next call will not start before %s. Therefore, your departure has been postponed to %s.
5018	Inexact beelines have been used for schedule calculation. %s of the distances must be calculated by the server. Repeat schedule calculation in a few minutes.
5023	You have changed your driving speed settings. Inexact beelines have thus been used for schedule calculation. %s of the distances still need to be calculated on the server. Repeat the schedule calculation in a few minutes.
5029	On %s arrival at '%s' has been moved to a later time.
5030	On %s departure from '%s' has been moved to an earlier time.
5031	There are no customers activated for portatour®.
5033	The schedule does not contain any calls. You can find possible reasons in the following warnings.
5034	None of your customers is due. Tip: The threshold for follow-up calls can be configured in the portatour® options.
5035	All customers are configured for manual scheduling. Change this setting in the portatour® options, or create reservations for some customers.
5036	The call intervals of all customers are set to 'none'. Change this setting in the portatour® options, or create reservations for some customers.
5037	There are no working hours set in the portatour® options.
5038	The planning period was shortened because portatour® can only optimize a maximum of 125 customer calls per week. To schedule for a longer period during one calculation, extend customers' call durations or shorten your working hours. Change the planning period accordingly in the scheduling parameters of the schedule.
5040	The calculation of your schedules already took %s minutes of server computation time today. To provide high-quality service to all users, server computation time is limited to %s minutes per user and day.
5041	This calculation of your schedule took %s seconds of server computation time. To provide a high-quality service to all users, server computation time is limited.
5042	%d appointments have been shortened: Duration of appointment %s has been shortened from %s to %s in order to reach the following appointment %s in time.
5045	For %d customers, the business hours are shorter than the call duration. These customers will not be scheduled automatically: %s
5046	%d customers do not have any business hours and thus will not be scheduled automatically: %s
5047	%s customers (%s%%) are 'preferred' with respect to the scheduling parameter 'interval adherence'. The maximum recommended ratio of preferred customers is %s%%. Reduce the number of preferred customers.
5048	%d appointments have not been scheduled: Appointment %s cannot be reached in time afterwards. Tip: Shorten the appointment to at most %s. Cannot be reached in time before appointment %s. Tip: Bring your working hours forward to no later than %s. Appointment %s could not be reached in time afterwards without exceeding your working hours. Tip: Extend your working hours to at least %s. Cannot be reached in time after previous appointment %s. Tip: Shorten the previous appointment to at most %s. Appointment %s could not be scheduled before this appointment and within your working hours. Tip: Bring your working hours forward to no later than %s. Cannot be reached in time after previous appointment %s without exceeding your working hours. Tip: Prolong the working hours to at least %s. Not reachable in time today. Tip: Postpone the appointment to no earlier than %s. Timeframe overlaps with %s. Cannot be reached in time from start location. Home location cannot be reached in time afterwards. End location cannot be reached in time afterwards. On %s, "%s" cannot be reached from "%s". Overlaps with %s.
5049	%d reservations have not been scheduled. You can find them in the reservations list.
5050	%d appointments have not been scheduled:
5051	Work break on %s could not be scheduled between appointments %s and %s within the necessary driving time (%d min). Tip: Move one of the appointments.
5053	Work breaks of %d more days could not be scheduled either.
5054	The range of your work break is too small in comparison to your customers' average call duration. This can lead to unwanted waiting times and circuitous routes. Prolong the range of your work break to at least %s (e.g. %s to %s), whereby you can leave the break's duration at %s.

Changelog

Version 1.3 (October 2026)

Changes from version 1.2.

Change type	Description
Change	Upgrade of the OpenAPI specification version from 3.0.4 to 3.1.1.
Addition	For all `geoPosition` properties: new output-only property `geocodePossibleDeviationMeters` with the possible deviation of the `geoPosition` in meters.
Change	For all geocoding operations and uploaded addresses without a `geoPosition`: new limit of 10,000 addresses per field rep and 24 hours. Exceeding returns HTTP status code 429.
Change	The type `enum` is now used for strings with a fixed set of allowed values, except for the `languageCultureName` of a field rep.
Addition	Responses now include the request ID `PT-RID`, which can be used to trace requests for support purposes.
Change	For clients generated based on the OpenAPI specification, several operations have improved names (e.g., `Calculate` becomes `CalculateSchedule`).
Addition	AccessTokens: create operations accept an optional `notes` field, which is shown in the portatour® Partner Portal.
Change	Geocode: the geocoding results use the object type LocationExport instead of Location.
Addition	SchedulingConstraints: new types `customerEventAnytimeInAWeek` and `blockerAnytimeInAWeek` are added.

Version 1.2 (October 2025)

Changes from version 1.1.

Change type	Description
Change	Upgrade of the OpenAPI specification version from 3.0.1 to 3.0.4.
Change	For all `address` properties in all `location` properties: `country` is no longer required.
Addition	Schedule: the result includes deviations, listing customers and scheduling constraints that were either not scheduled at all or scheduled differently than provided in the input data.
Change	Schedule: values for `fieldRepCurrentLocalDateTime` in `calculationParameters` must be between UTC -13h and UTC +15h.
Change	Schedule: values for `scheduleBeginAt` in `calculationParameters` must be between -24 hours and +365 days relative to `fieldRepCurrentLocalDateTime`.
Change	Schedule: The schedule response row types `scheduleWorkBreakRow` and `scheduleWaitRow` are removed. For the `scheduleDriveRow` type, the `interruption` property is introduced instead.
Change	SchedulingConstraints: for all types, the property `location` in `locationInformation` is renamed to `customLocation`. This change does not apply to exported scheduling constraints.
Change	SchedulingConstraints: for the types `deviatingStartOfDay`, `deviatingEndOfDay`, `overnightStay`, and `generic`, the `preferredOvernightLocationId` property has been moved to `locationInformation`.
Change	FieldReps: the object type of the property `homeLocation` is renamed from Location to HomeLocation.
Change	FieldReps: the object type of the property `address` in `homeLocation` is renamed from Address to HomeAddress.

Version 1.1 (May 2024, Deprecated)

End of Life: 30th April 2028.

Changes from version 1.0.

Change type	Description
Change	Schedule: allowed values for `schedulePeriodDays` in `calculationParameters` now depend on the `edition` of the organization.
Change	Schedule: default value for `trafficConditionsForFirstRide` in `calculationParameters` is now `"TypicalTraffic"` instead of `"CurrentTraffic"`.
Addition	Organizations: `edition` now also supports values `"Basic"` and `"Professional"`. For further information see Editions.
Change	Geocode: Limit the maximum number of addresses to 2,000 per request.
Change	FieldReps: `workingHours` are no longer required.
Addition	Error Codes: new `errorCode` `"2000"` for requests that have edition violations for Schedule, Organizations, and FieldReps.

Version 1.0 (October 2023, Deprecated)

End of Life: 30th April 2027.

Changes from version 0.9 (BETA).

Change type	Description
Change	For all requests, with `geoPosition` object: `geocodeWarning` property is now output-only, if provided in a request, the request will be rejected with HTTP status code 400
Change	For all responses, with `errorInformation` object: renamed property `id` to `errorCode`
Addition	Schedule: new required parameter `fieldRepCurrentLocalDateTime` in `calculationParameters`
Change	Schedule: `id` of the `schedule` response object changed to non-null string
Change	Schedule: all `timeFrom` and `timeTo` properties in the response rows are no longer nullable
Change	Schedule: all `displayName` properties in the response rows are no longer nullable
Change	Schedule, retrieve async schedule calculation result: in response object `pollScheduleCalculationResult` renamed property `type` to `status`
Change	Schedule, retrieve async schedule calculation result: in response object `pollScheduleCalculationResult` property `status` no longer supports `"NotFound"` value, HTTP status code 404 is used instead
Change	Organizations, add or update an organization: successful responses are now always HTTP status code 200
Change	Geocode, async geocode result: in response object `pollGeocodeCalculationResult` renamed property `type` to `status`
Change	Geocode, async geocode result: in response object `pollGeocodeCalculationResult` property `status` no longer supports `"Failed"` and `"NotFound"` values, HTTP status codes 400 and 404 are used instead
Deletion	Geocode, async geocode result: in response object `pollGeocodeCalculationResult` properties `errorId` and `errorMessages` are removed, `errorInformation` and HTTP status codes 4xx and 5xx are used instead
Change	FieldReps, add or update a field rep: successful responses are now always HTTP status code 200
Change	Export: the postfix `"Export"` is now added to the names of all export response objects and some of their property type names

How-to Guides

Guides to help you get started with the API.

Code samples are provided in C# and using OpenAPI or HttpClient.

To create the OpenAPI client, see how to create an OpenAPI client.

How to handle errors?

If you are using a generated OpenAPI client, you can use the returned ErrorInformation to get detailed information about the error. If you are accessing the API directly without an OpenAPI client, always read the response body to get the ErrorInformation.

The list of possible errors shows the meaning of the error codes.

C# using OpenAPI C# using HttpClient

var accessToken = "INVALID_ACCESS_TOKEN";
var organizationId = "ExampleOrganizationId001";

try
{
    var httpClient = new HttpClient();
    httpClient.DefaultRequestHeaders.Add("pt-access-token", accessToken);
    var baseAddress = "https://api.portatour.net";
    var client = new OpenAPIClient(baseAddress, httpClient);

    // throws the ApiException<ErrorInformation>
    var allFieldReps = await client.GetAllFieldRepsAsync(organizationId);

    foreach (var fp in allFieldReps)
    {
        Console.WriteLine($"{fp.Id};{fp.Name};{fp.LanguageCultureName}");
    }
}
catch (ApiException<ErrorInformation> apiExc)
{
    Console.WriteLine("ApiException of type ErrorInformation raised:");
    Console.WriteLine($"Error Code: {apiExc.Result.ErrorCode}");
    Console.WriteLine($"Message: {apiExc.Result.Message}");
    Console.WriteLine($"HTTP StatusCode: {apiExc.Result.StatusCode} ");
    Console.WriteLine($"CorrelationId: {apiExc.Result.CorrelationId}");
}
catch (Exception exc)
{
    Console.WriteLine($"Generic Exception was raised: {exc.Message}");
}

// Output:
//      ApiException of type ErrorInformation raised:
//      Error Code: 1300
//      Message: Access token not valid
//      HTTP StatusCode: 401
//      CorrelationId: RID-ZL-I0HoytnP-wqNKBQjCpgAAA2k

var accessToken = "INVALID_ACCESS_TOKEN";
var organizationId = "ExampleOrganizationId001";

var baseAddress = "https://api.portatour.net";
var httpClient = new HttpClient
{
    BaseAddress = new Uri(baseAddress)
};
httpClient.DefaultRequestHeaders.Add("pt-access-token", accessToken);

var result = await httpClient
    .GetAsync($"/1.3/export/organizations/{organizationId}/fieldReps");

if (result.IsSuccessStatusCode)
{
    Console.WriteLine(await result.Content.ReadAsStringAsync());
}
else
{
    Console.WriteLine($"Failed to get the field reps for organization {organizationId}.");
    Console.WriteLine($"HTTP StatusCode: {(int)result.StatusCode}, {result.ReasonPhrase}");
    Console.WriteLine($"Additional information:{Environment.NewLine}" +
        $"{await result.Content.ReadAsStringAsync()}");
}

// Output:
//      Failed to get the field reps for organization ExampleOrganizationId001.
//      HTTP StatusCode: 401, Unauthorized
//      Additional information:
//      {
//          "statusCode": 401,
//          "message": "Access token not valid",
//          "errorCode": "1300",
//          "correlationId": "RID-ZL-I0HoytnP-wqNKBQjCpgAAA2k"
//      }

How to use an access token?

To use the API, requests must include pt-access-token header with a valid access token.

GET https://api.portatour.net/1.3/export/organizations/{organizationId}/fieldReps/{fieldRepId}/customers
User-Agent: user-agent
Content-Type: application/json; charset=utf-8
pt-access-token: <YOUR_ACCESS_TOKEN>

The code samples add the pt-access-token to the header.

Set accessToken to your access token generated by using the partner portal or the AccessTokens operations.

C# using OpenAPI C# using HttpClient

var accessToken = "<YOUR_ACCESSTOKEN_GOES_HERE>";

var baseAddress = "https://api.portatour.net";
var httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Add("pt-access-token", accessToken);

var client = new OpenAPIClient(baseAddress, httpClient);

var accessToken = "<YOUR_ACCESSTOKEN_GOES_HERE>";

var baseAddress = "https://api.portatour.net";
var httpClient = new HttpClient
{
    BaseAddress = new Uri(baseAddress)
};
httpClient.DefaultRequestHeaders.Add("pt-access-token", accessToken);

How to create an organization?

The code samples below show how to create an organization using the add or update organization operation.

Set accessToken to your access token, which must be of scope partner.

C# using OpenAPI C# using HttpClient

var accessToken = "<YOUR_ACCESSTOKEN_GOES_HERE>";
var organizationId = "ExampleOrganizationId001";

var organization = new Organization()
{
    Name = "Example Inc.",
    Edition = Edition.Ultimate,
    MapRegion = MapRegion.NorthAmerica,
    MaxFieldRepCount = 10,
    EnabledUntilUTC = "2030-12-31T23:59"
};
try
{
    var baseAddress = "https://api.portatour.net";
    var httpClient = new HttpClient();
    httpClient.DefaultRequestHeaders.Add("pt-access-token", accessToken);
    var client = new OpenAPIClient(baseAddress, httpClient);

    await client.AddOrUpdateOrganizationAsync(organizationId, organization);
    Console.WriteLine($"Organization {organizationId} successfully created.");
}
catch (ApiException<ErrorInformation> apiExc)
{
    // handle non-success result
}

// Output:
//      Organization ExampleOrganizationId001 successfully created.

var accessToken = "<YOUR_ACCESSTOKEN_GOES_HERE>";
var organizationId = "ExampleOrganizationId001";

var organization =
    @"{
        ""name"": ""Example Inc."",
        ""edition"": ""Ultimate"",
        ""mapRegion"": ""NorthAmerica"",
        ""maxFieldRepCount"": 10,
        ""enabledUntilUTC"": ""2030-12-31T23:59""
    }";
var content = new StringContent(organization, System.Text.Encoding.UTF8, "application/json");

var baseAddress = "https://api.portatour.net";
var httpClient = new HttpClient
{
    BaseAddress = new Uri(baseAddress)
};
httpClient.DefaultRequestHeaders.Add("pt-access-token", accessToken);

var result = await httpClient.PutAsync($"/1.3/organizations/{organizationId}", content);
if (result.IsSuccessStatusCode)
{
    Console.WriteLine($"HTTP Response: {(int)result.StatusCode}, {result.ReasonPhrase}");
    Console.WriteLine($"Organization {organizationId} successfully created.");
}
else
{
    // handle non-success result
}

// Output:
//      HTTP Response: 200, OK
//      Organization ExampleOrganizationId001 successfully created.

How to create a field rep?

The code samples below show how to create a field rep using the add or update field rep operation.

Set accessToken to your access token and organizationId to your organizationId.

C# using OpenAPI C# using HttpClient

var accessToken = "<YOUR_ACCESSTOKEN_GOES_HERE>";
var organizationId = "<YOUR_ORGANIZATIONID_GOES_HERE>";
var fieldRepId = "ExampleFieldRepId001";

var fieldRep = new FieldRep()
{
    Name = "Alice Smith",
    LanguageCultureName = "en-US",
    HomeLocation = new HomeLocation()
    {
        Address = new HomeAddress()
        {
            StreetWithHouseNumber = "5366 College Ave",
            PostalCode = "94618",
            City = "Oakland",
            State = "CA",
            Country = "US"
        }
    },
    WorkingHours = new WorkingHours()
    {
        Monday = new DailyTimeRange()
        {
            From = "08:00:00",
            To = "18:00:00"
        }
    }
};
try
{
    var httpClient = new HttpClient();
    httpClient.DefaultRequestHeaders.Add("pt-access-token", accessToken);
    var baseAddress = "https://api.portatour.net";
    var client = new OpenAPIClient(baseAddress, httpClient);

    await client.AddOrUpdateFieldRepAsync(organizationId, fieldRepId, fieldRep);
    Console.WriteLine($"FieldRep {fieldRepId} successfully created.");
}
catch (ApiException<ErrorInformation> apiExc)
{
    // handle non-success result
}

// Output:
//      FieldRep ExampleFieldRepId001 successfully created.

var accessToken = "<YOUR_ACCESSTOKEN_GOES_HERE>";
var organizationId = "<YOUR_ORGANIZATIONID_GOES_HERE>";
var fieldRepId = "ExampleFieldRepId001";

var fieldRep =
    @"{
        ""name"": ""Alice Smith"",
        ""languageCultureName"": ""en-US"",
        ""homeLocation"": {
            ""address"": {
                ""streetWithHouseNumber"": ""5366 College Ave"",
                ""postalCode"": ""94618"",
                ""city"": ""Oakland"",
                ""state"": ""CA"",
                ""country"": ""US""
            }
        },
        ""workingHours"": {
            ""monday"": {
                ""from"": ""08:00:00"",
                ""to"": ""18:00:00""
            }
        }
    }";
var content = new StringContent(fieldRep, System.Text.Encoding.UTF8, "application/json");

var baseAddress = "https://api.portatour.net";
var httpClient = new HttpClient
{
    BaseAddress = new Uri(baseAddress)
};
httpClient.DefaultRequestHeaders.Add("pt-access-token", accessToken);

var result = await httpClient.PutAsync($"/1.3/organizations/{organizationId}/fieldReps/{fieldRepId}", content);
if (result.IsSuccessStatusCode)
{
    Console.WriteLine($"HTTP Response: {(int)result.StatusCode}, {result.ReasonPhrase}");
    Console.WriteLine($"FieldRep {fieldRepId} successfully created.");
}
else
{
    // handle non-success status here
}

// Output:
//      HTTP Response: 200, OK
//      FieldRep ExampleFieldRepId001 successfully created.

How to calculate a schedule?

The code samples below show how to calculate a schedule using the calculate and retrieve a schedule operation.

In order to use this sample, a field rep must exist. The operation uses customers and calculation parameters that are provided.

Set accessToken to your access token, organizationId to your organizationId and fieldRepId to your fieldRepId.

C# using OpenAPI C# using HttpClient

var accessToken = "<YOUR_ACCESSTOKEN_GOES_HERE>";
var organizationId = "<YOUR_ORGANIZATIONID_GOES_HERE>";
var fieldRepId = "<YOUR_FIELDREPID_GOES_HERE>";

var scheduleCalculationRequest = new ScheduleCalculationRequest()
{
    CalculationParameters = new CalculationParameters()
    {
        FieldRepCurrentLocalDateTime = DateTime.Now.ToString("yyyy-MM-ddTHH:mm"),
        ScheduleBeginAt = DateTime.Now.AddDays(1).ToString("yyyy-MM-ddT08:00"),
        SchedulePeriodDays = 7,
    },
    NewDataSet = new NewDataSet()
    {
        Customers = new List<Customer>()
        {
            new Customer()
            {
                Id = "ExampleCustomerId001",
                Name = "Williams, Derek",
                Location = new Location()
                {
                    Address = new Address()
                    {
                        SingleLineAddress = "140 2nd St, 94971 Tomales, California",
                        Country = "USA",
                    }
                },
                ActivatedOn = "2022-08-21",
                CallInterval = new CallInterval()
                {
                    Days = 30
                },
                CallDurationMinutes = 15,
                CallingHours = new CallingHours()
                {
                    MondayPeriod1 = new DailyCallingHours()
                    {
                        From = "08:00:00",
                        To = "18:00:00"
                    }
                }
            }
        }
    }
};

try
{
    var httpClient = new HttpClient();
    httpClient.DefaultRequestHeaders.Add("pt-access-token", accessToken);
    var baseAddress = "https://api.portatour.net";
    var client = new OpenAPIClient(baseAddress, httpClient);

    var schedule = await client.CalculateScheduleAsync(organizationId, fieldRepId, scheduleCalculationRequest);
    foreach (var day in schedule.Days)
    {
        Console.WriteLine($"Day: {day.Day}");
        Console.WriteLine();
        foreach (var row in day.Rows)
        {
            switch (row.Type)
            {
                case ScheduleRowType.Stop:
                    Console.WriteLine($"STOP at {row.Stop.DisplayName} from {row.Stop.TimeFrom} to {row.Stop.TimeTo}");
                    // handle Stop
                    break;
                case ScheduleRowType.Drive:
                    Console.WriteLine($"DRIVE from {row.Drive.TimeFrom} to {row.Drive.TimeTo}");
                    // handle Drive
                    break;
                case ScheduleRowType.SchedulingConstraintWithoutLocation:
                    // handle SchedulingConstraintWithoutLocation
                    break;
                default:
                    throw new NotSupportedException();
            }
        }
    }
}
catch (ApiException<ErrorInformation> apiExc)
{
    // handle non-success result
}

// Output:
//      Day: 2023-09-21
//
//      STOP at Home location from 08:00:00 to 08:00:00
//      DRIVE from 08:00:00 to 09:22:57
//      STOP at Williams, Derek from 09:22:57 to 09:37:57
//      DRIVE from 09:37:57 to 10:54:56
//      STOP at Home location from 10:54:56 to 10:54:56
// ...

var accessToken = "<YOUR_ACCESSTOKEN_GOES_HERE>";
var organizationId = "<YOUR_ORGANIZATIONID_GOES_HERE>";
var fieldRepId = "<YOUR_FIELDREPID_GOES_HERE>";

var now = DateTime.Now.ToString("yyyy-MM-ddTHH:mm");
var begin = DateTime.Now.AddDays(1).ToString("yyyy-MM-ddT08:00");
var scheduleCalculationRequest =
    @"{
        ""calculationParameters"": {
            ""fieldRepCurrentLocalDateTime"": """ + now + @""",
            ""scheduleBeginAt"": """ + begin + @""",
            ""schedulePeriodDays"": 7
        },
        ""newDataSet"": {
            ""customers"":
            [{
                ""id"": ""ExampleCustomerId001"",
                ""name"": ""Williams, Derek"",
                ""location"": {
                    ""address"": {
                        ""singleLineAddress"": ""140 2nd St, 94971 Tomales, California"",
                        ""country"": ""USA""
                    }
                },
                ""activatedOn"": ""2022-08-21"",
                ""callInterval"": {
                    ""days"": 30
                },
                ""callDurationMinutes"": 15,
                ""callingHours"": {
                    ""mondayPeriod1"": {
                        ""from"": ""08:00:00"",
                        ""to"": ""18:00:00""
                    }
                }
            }]
        }
    }";
var content = new StringContent(scheduleCalculationRequest, System.Text.Encoding.UTF8, "application/json");

var baseAddress = "https://api.portatour.net";
var httpClient = new HttpClient
{
    BaseAddress = new Uri(baseAddress)
};
httpClient.DefaultRequestHeaders.Add("pt-access-token", accessToken);

var result = await httpClient
    .PostAsync($"/1.3/organizations/{organizationId}/fieldReps/{fieldRepId}/schedule/calculate", content);
Console.WriteLine($"HTTP Response: {(int)result.StatusCode}, {result.ReasonPhrase}");

var schedule = await result.Content.ReadAsStringAsync();
Console.WriteLine(schedule);

// Output:
// {
//    "id":"{98D9E650-9E0F-4EB2-B4A4-5DEB1B8E62A5}",
//    "days":[
//       {
//          "day":"2023-09-21",
//          "rows":[
//             {
//                "type":"Stop",
//                "stop":{
//                   "timeFrom":"08:00:00",
//                   "timeTo":"08:00:00",
//                   "stopType":"DepartureFromHome",
//                   "displayName":"Home location",
//                   "location":{
//                      "address":{
//                         "streetWithHouseNumber":"5366 College Ave",
//                         "postalCode":"94618",
//                         "city":"Oakland",
//                         "state":"CA",
//                         "country":"US"
//                      },
//                      "geoPosition":{
//                         "latitude":37.839301,
//                         "longitude":-122.251317
//                      }
//                   }
//                }
//             },
//             {
//                "type":"Drive",
//                "drive":{
//                   "timeFrom":"08:00:00",
//                   "timeTo":"09:22:57",
//                   "distanceMeters":0,
//                   "routingType":"TypicalTraffic",
//                   "routePolyline":""
//                }
//             },
//             {
//                "type":"Stop",
//                "stop":{
//                   "timeFrom":"09:22:57",
//                   "timeTo":"09:37:57",
//                   "stopType":"StopAtCustomer",
//                   "displayName":"Williams, Derek",
//                   "location":{
//                      "address":{
//                         "streetWithHouseNumber":"140 2nd St",
//                         "postalCode":"94971",
//                         "city":"Tomales",
//                         "state":"California",
//                         "country":"USA"
//                      },
//                      "geoPosition":{
//                         "latitude":38.2482,
//                         "longitude":-122.906468
//                      }
//                   },
//                   "customerId":"ExampleCustomerId001"
//                }
//             },
//             {
//                "type":"Drive",
//                "drive":{
//                   "timeFrom":"09:37:57",
//                   "timeTo":"10:54:56",
//                   "distanceMeters":0,
//                   "routingType":"TypicalTraffic",
//                   "routePolyline":""
//                }
//             },
//             {
//                "type":"Stop",
//                "stop":{
//                   "timeFrom":"10:54:56",
//                   "timeTo":"10:54:56",
//                   "stopType":"DepartureFromHome",
//                   "displayName":"Home location",
//                   "location":{
//                      "address":{
//                         "streetWithHouseNumber":"5366 College Ave",
//                         "postalCode":"94618",
//                         "city":"Oakland",
//                         "state":"CA",
//                         "country":"US"
//                      },
//                      "geoPosition":{
//                         "latitude":37.839301,
//                         "longitude":-122.251317
//                      }
//                   }
//                }
//             }
//          ]
//       }
// ...

How to use scheduling constraints?

The code samples below show how to set scheduling constraints using the set scheduling constraints operation.

In order to use this sample, a field rep must exist.

Set accessToken to your access token, organizationId to your organizationId and fieldRepId to your fieldRepId.

C# using OpenAPI C# using HttpClient

var accessToken = "<YOUR_ACCESSTOKEN_GOES_HERE>";
var organizationId = "<YOUR_ORGANIZATIONID_GOES_HERE>";
var fieldRepId = "<YOUR_FIELDREPID_GOES_HERE>";

var schedulingConstraints = new List<SchedulingConstraint>()
{
    new SchedulingConstraint()
    {
        // customer event, i.e. an appointment at fixed date and time
        CustomerEvent = new CustomerEvent()
        {
            Id = "ExampleConstraintId001",
            Subject = "Quarterly review",
            StartDate = "2024-03-18",
            BeginAt = "10:00",
            EndAt = "11:00",
            CustomerId = "ExampleCustomerId001",
            LocationInformation = new CustomerEventLocation()
            {
                LocationType = CustomerEventLocationType.CustomerLocation
            }
        }
    },
    new SchedulingConstraint()
    {
        // customer event, i.e. an appointment scheduled on a fixed day at an opportune time
        CustomerEventAnytimeOnADay = new CustomerEventAnytimeOnADay()
        {
            Id = "ExampleConstraintId002",
            Subject = "Short visit",
            Date = "2024-03-19",
            DurationMinutes = 30,
            CustomerId = "ExampleCustomerId001",
            LocationInformation = new CustomerEventLocation()
            {
                LocationType = CustomerEventLocationType.CustomerLocation
            }
        }
    },
    new SchedulingConstraint()
    {
        // blocker, i.e. bank holiday or vacation day
        Blocker = new Blocker()
        {
            Id = "ExampleConstraintId003",
            Subject = "Vacation day",
            StartDate = "2024-03-22",
            BeginAt = "00:00",
            EndAt = "23:59",
            LocationInformation = new BlockerLocation()
            {
                LocationType = BlockerLocationType.HomeLocation
            }
        }
    }
};

try
{
    var httpClient = new HttpClient();
    httpClient.DefaultRequestHeaders.Add("pt-access-token", accessToken);
    var baseAddress = "https://api.portatour.net";
    var client = new OpenAPIClient(baseAddress, httpClient);

    await client.SetSchedulingConstraintsAsync(organizationId, fieldRepId, schedulingConstraints);
    Console.WriteLine($"Scheduling constraints for field rep {fieldRepId} successfully set.");
}
catch (ApiException<ErrorInformation> apiExc)
{
    // handle non-success result
}

// Output:
//      Scheduling constraints for field rep ExampleFieldRepId001 successfully set.

var accessToken = "<YOUR_ACCESSTOKEN_GOES_HERE>";
var organizationId = "<YOUR_ORGANIZATIONID_GOES_HERE>";
var fieldRepId = "<YOUR_FIELDREPID_GOES_HERE>";

// customer event, i.e. an appointment at fixed date and time
// customer event, i.e. an appointment scheduled on a fixed day at an opportune time
// blocker, i.e. bank holiday or vacation day
var schedulingConstraints =
    @"[
        {
            ""customerEvent"": {
                ""id"": ""ExampleConstraintId001"",
                ""subject"": ""Quarterly review"",
                ""startDate"": ""2024-03-18"",
                ""beginAt"": ""10:00"",
                ""endAt"": ""11:00"",
                ""customerId"": ""ExampleCustomerId001"",
                ""locationInformation"": {
                    ""locationType"": ""CustomerLocation""
                }
            }
        },
        {
            ""customerEventAnytimeOnADay"": {
                ""id"": ""ExampleConstraintId002"",
                ""subject"": ""Short visit"",
                ""date"": ""2024-03-19"",
                ""durationMinutes"": 30,
                ""customerId"": ""ExampleCustomerId001"",
                ""locationInformation"": {
                    ""locationType"": ""CustomerLocation""
                }
            }
        },
        {
            ""blocker"": {
                ""id"": ""ExampleConstraintId003"",
                ""subject"": ""Vacation day"",
                ""startDate"": ""2024-03-22"",
                ""beginAt"": ""00:00"",
                ""endAt"": ""23:59"",
                ""locationInformation"": {
                    ""locationType"": ""HomeLocation""
                }
            }
        }
    ]";
var content = new StringContent(schedulingConstraints, System.Text.Encoding.UTF8, "application/json");

var baseAddress = "https://api.portatour.net";
var httpClient = new HttpClient
{
    BaseAddress = new Uri(baseAddress)
};
httpClient.DefaultRequestHeaders.Add("pt-access-token", accessToken);

var result = await httpClient
    .PutAsync($"/1.3/organizations/{organizationId}/fieldReps/{fieldRepId}/schedulingConstraints", content);
if (result.IsSuccessStatusCode)
{
    Console.WriteLine($"HTTP Response: {(int)result.StatusCode}, {result.ReasonPhrase}");
    Console.WriteLine($"Scheduling constraints for field rep {fieldRepId} successfully set.");
}
else
{
    // handle non-success result
}

// Output:
//      HTTP Response: 200, OK
//      Scheduling constraints for field rep ExampleFieldRepId001 successfully set.

How to create an OpenAPI client?

Microsoft Visual Studio (Version 2026)

To add the OpenAPI specification as a "Connected Service" to your project in Microsoft Visual Studio, follow the steps.

right-click your project in the "Solution Explorer" and
select "Add" from the menu
locate the "Connected Service" entry and click on it

A dialog will appear where you can add a service reference to an OpenAPI service.

click the "plus" symbol
another dialog appears where you can select the kind of service you want to add
- for our API, you have to select OpenAPI

The dialog with the title "Add new OpenAPI service reference" appears.

if you downloaded the spec file (portatour.json) you can select the location of the file
if you want to connect directly to the https address, select the URL text box and enter the address to the portatour.json file on our server

In the last dialog, enter the following information.

the namespace for the generated client
the name of the client class, that will be generated
the language for which you want to use the client (C# / Typescript).
for additional code generation options, please read Microsoft's documentation .NET OpenAPI tool command reference and installation

Other client generators

For languages other than C# and TypeScript, see https://github.com/OpenAPITools/openapi-generator#readme or find other generators.

FAQ

How to prioritize customers in schedule?

To ensure that customers are adequately prioritized in the schedule, follow one or more of these strategies:

Prioritize by callInterval: Choose call intervals based on the customer’s ABC classification, using shorter intervals for higher-priority customers. Note: The lastCallOn date is used to calculate the customer’s "due" status relative to their call interval. If the territory is too large, i.e. if there are too many customers or the call intervals are too short, it may not be possible to adhere to the customer's call intervals. As a result, calls will be scheduled later than expected. If the territory is too small, customers may be scheduled before their call intervals are fully reached. However, they will never be scheduled before they reach the field rep's generalCustomerSchedulingSettings.dueAfterLastCallIntervalPercent. For instance, a customer with a 100-day interval and a field rep with a dueAfterLastCallIntervalPercent of 80% could be scheduled 80 days after the last call. The schedule calculation preserves the relative proportions regardless of the territory size. For instance, a 30-day customer will still be visited twice as often as a 60-day customer.
Enable isAdherencePreferred: This helps prevent call intervals from being exceeded for certain customers, even when the territory is too large. This setting can be used for customers who are contractually required to be called within a specific call interval. Use the isAdherencePreferred flag sparingly. It should only be applied to high-priority customers for whom delayed calls are unacceptable. This setting is recommended for no more than 20% of regularly scheduled customers. Overuse may reduce its effectiveness and driving time optimization may be deprioritized. Note: Territories should be properly dimensioned to support better scheduling and adherence behavior. See portatour® Territory Optimization.
Force a call with doForceCall: For customers that should be included in the next schedule regardless of their call intervals, use the doForceCall flag. Customers with this flag are prioritized over customers that would be scheduled according to their call intervals. If not all customers marked with doForceCall can be scheduled, the schedule calculation will include as many as possible, and list all those which could not be included in the schedule in deviations.unscheduledCustomersWithDoForceCall. Additionally, a schedule message with the id 5049 will be returned.

What happens to a field rep when an organization's edition is downgraded?

The organization's edition determines which features and limits are available. When an organization's edition is downgraded, either in the partner portal or via the API (AddOrUpdateOrganization), all existing field reps and their data remain unchanged.

Edition limits are enforced when a schedule is calculated (CalculateSchedule or StartScheduleCalculation). If a field rep's data exceeds the limits or features available in the current edition, the calculation fails with an HTTP 400 response and a corresponding error message. To calculate a schedule, upgrade the organization's edition or update the data and feature usage according to the current edition limits.