Assign route to a vehicle

This endpoint creates a new route and route steps and assigns them to the specified vehicle.

Specifying the path

The path needs to be specifyed in each step defined. There are two ways to do this:

Defining the polyline
A polyline may be obtained from the maps service provider.
If you decide to specify the polylines, you need to specify them for every step in the route - not just a for a few steps ; otherwise, Frotcom will use the starts and arrive points, ignoring any polyline that you may have specified.
If you choose not to define the polyline for every step, then you need to define the starts and arrive points ; otherwise, the operation will fail with a "Bad Request" HTTP response.
Specifying the starts and arrive points
If you don't define the polyline, then you need to define these points. You may define these endpoint in two ways:
1. Use the ID of a place registered in the company
  If you specify the ID of a place, then it's coordinates will be used as the coordinates of the point being defined.
2. Use the GPS coordinates of the point. If you specify the GPS coordinates, these will prevail over the ID of the place.
  If you specify the GPS coordinates, then these will be used as the coordinates of the point being defined.
  If you specify both, the place ID and and the GPS coordinates, then then the GPS coordinates will be used and the place ID will be ignored.

Parameters

vehicleId

int The ID if the vehicle to which the route should be assigned. This parameter is specified as part of the request's URL.

sendToWFMNAV

If true it will send route alert to vehicle terminal WFM/Navigator.
This parameter is specified as part of the request's URL and is specified in the query string. bool

route

Specifies the caracteristics of the route and the creation options

object yes

Example:

{
    "code":"string",
    "name": "string",
    "polyline": "string",
    "hereStepPolylines":["string"],
    "polylineProvider":"string",
    "polylineProviderVersion": "string",
    "accountPolylineProvider": "string",
    "accountPolylineProviderVersion": "string",
    "stepId" 0,
    "routeId": 0
    "steps": [
      {
        "createCorridor": false,
        "corridorWidth"; 0.0,
        "starts":
          {
            "placeId": 0,
            "address": "string",
            "planned": "2023-06-02T12:19:26.688Z",
            "coordinates" :
            {
                "latitude": 0.0,
                "longitude": 0.0,
            }
          },
        "arrive":
            {
                "placeId": 0,
                "address": "string",
                "planned": "2023-06-02T12:19:26.688Z",
                "coordinates" :
                {
                    "latitude": 0.0,
                    "longitude": 0.0,
                }
            },
        "times":
        {
            "mileage": 0,
            "duration": 0,
            "breaks": 0,
            "stopOver": 0,
            "defaultBreak": 0
        },
        "notifications":
        {
            "mode": "time",
            "delta": 0,
            "subject": "string"
            "message": "string;
            "warnings":
            {
                "emails": "string",
                "phones": "string"
            },
            "others":
            {
                "emails": "string",
                "phones": "string"
            }
        },
        "alarms": 
        {
            "contacts": 
            {
                "emails": "string",
                "phones": "string"
            },
            "terminal": "notSendAlarm",
            "sound": 0,
            "playSound": true,
            "confirmation": true,
            "form": "string", 
            "formInterval": 0
            "warningATDBefore": true,
            "warningATDBeforeDuration": 0,
            "warningATDAfter": true,
            "warningATDAfterDuration": 0,
            "warningETABefore": true,
            "warningETABeforeDuration": 0,
            "warningETAAfter: true, 
            "warningETAAfterDuration": 0,
            "warningETATolerance": true,
            "warningETAAfterImidiately": true, 
            "warningATDAfterImidiately": true
        },
        "messages":
        {
            "message" : "string",
            "scheduleArriveTime": true,
            "destinationPoint" : true,
            "jobId" int: Job Id
            "taskId" int: Task Id
        },
        "dragPoints":
            [
                {
                    "latitude": 0,
                    "longitude" : 0
                }
            ]
        },
        "altDirIndex": 0,
    ],
    "options": General Route directions options
    {
        "avoidHighways": false,
        "reorderingWaypointsAllowed": false,
        "avoidTolls": false,
        "avoidFerries": false,
        "costOptimized": false,
        "vehicleClassId": 0,
        "vehicleProfileId": 0,
        "useDrivingTimeRestrictionsRules": true,
        "useExistingVehicleDrivingTime": false,
        "vehicleDrivingTimeId": 0,
        "coverMaxDistance": false,
        "useTeamDrivers": false,
        "useClientTimes": false,
        "stepToleranceStartTimeBefore": "string",
        "stepToleranceStartTimeAfter": "string"
    },
    "field1": "string"
    "field2": "string"
    "field3": "string"
}

Field Description

vehicleId The ID of the vehicle to where the route should be assigned string

code Route code string 10 no

name Name of the route. The name of the route can not be empty or nulll. string 50 yes

hereStepPolylines Steps polyline inside a list.(only used internally) list of string no

polylineProvider The source of the route polyline, which can either be Google or Here.(only used internally) string no

polylineProviderVersion The version of the polyline depends on the provider. If the provider is Google, the version is SimplePolyline. If it is Here, the version is FlexiblePolyline. (only used internally) string no

accountPolylineProvider The map account provider used for the route polyline.(only used internally) string no

accountPolylineProviderVersion The version of the route polyline depends on the account provider. If the provider is Google, the version is SimplePolyline. If it is Here, the version is FlexiblePolyline. (only used internally) string no

routeId Route Id if assigning to an existent route int no

steps Array with all Route Step Definitions Array of objects no

steps[i].createCorridor Specifies if a corridor should be created for the step bool 10 no

steps[i].corridorWith The width of the corridor, in Kilometers double if createCorridor is set to true

polyline Step polyline drawing string no

steps[i].starts Definition of the coordinates of the starting location of the step object When the polyline of the step is not defined

steps[i].starts.placeId The ID of a company's place that defines the starting place integer > 0 If coordinates is not specified

steps[i].starts.address If departure of the place exists, put the name of place ; otherwise, the name of the departure location address string no

steps[i].starts.planned The moment when it is expected that the vehicle starts the step. date/time yes

steps[i].starts.coordinates The GPS coordinates of the arrival location of the step. object If placeId is not defined

steps[i].starts.coordinates.latitude The latitude of the starting location of the step. decimal yes

steps[i].starts.coordinates.longitude The longitude of the starting location of the step. decimal yes

steps[i].arrive Definition of the coordinates of the starting location of the step. object When the polyline of the step is not defined

steps[i].arrive.placeId The ID of a company's place that defines the place of arrival. integer > 0 If coordinates is not specified

steps[i].arrive.address If end of the place exists, put the name of place, otherwise, the name of the end location address. string no

steps[i].arrive.planned The moment when it is expected that the vehicle reaches the end of the step. date/time no

steps[i].arrive.coordinates The GPS coordinates of the arrival location of the step. object In placeId is not defined

steps[i].arrive.coordinates.latitude The latitude of the arrival location of the step. decimal yes

steps[i].arrive.coordinates.longitude The longitude of the arrival location of the step. decimal yes

steps[i].times object no

steps[i].times.mileage Mileage in meters. int no

steps[i].times.duration Duration in minutes. int no

steps[i].times.breaks Breaks in minutes. int no

steps[i].times.stopOver Stop over value in minutes. int no

steps[i].times.defaultBreak If breaks time is not defined, then used the default time. int no

steps[i].notifications object no

steps[i].notifications.mode

This field defines the mode of sending notifications before estimated arrival.

Name	Description
none	Specifies that no notifications should be triggered.
time	Specifies that the notifications are triggered based on time.
distance	Specifies that the notifications are triggered based on distance.

enum

steps[i].notifications.delta If mode is set to time, then this value is assumed to be in minues;
If mode is set to distance, then this value is assumed to be in Kilometers int if mode is not none

steps[i].notifications.subject Subject of the notification. string no

steps[i].notifications.message Message of the notification string no 256 characters

steps[i].notifications object no

steps[i].notifications.warnings object no

steps[i].notifications.warnings.emails Specify one or multiple emails, splitting each with ;. string no

steps[i].notifications.warnings.phones Specify one or multiple phone numbers, splitting each with ; string no

steps[i].notifications.others object no

steps[i].notifications.others.emails Specify one or multiple emails, splitting each with ;. string no

steps[i].notifications.others.phones Specify one or multiple phone numbers, splitting each with ;. string no

steps[i].alarms Route Step alarm configurations object no

steps[i].alarms.contacts Notification contacts to use in case of alarm object no

steps[i].alarms.contacts.emails Specify one or multiple emails, splitting each with ; string no

steps[i].alarms.contacts.phones Specifies one or multiple phone numbers, splitting each with ; string no

steps[i].alarms.terminal

When specified, tells the endpoint to which terminal the alarm should be send

Name	Description
notSendAlarm	Do not send alarm
sendAlarmToWorkForceManagementTerminal	Send Alarm to workforce management terminal
sendAlarmToNavigator	Send alarm to navigator
soundBuzzer	Sound Buzzer

string

steps[i].alarms.sound Allows to specify the ID of a sound. int no

steps[i].alarms.playSound If assigned to true and the terminal type selected is sendAlarmToWorkForceManagementTerminal, the alarm will be notified with sound. bool no

steps[i].alarms.confirmation When the terminal type selected is sendAlarmToWorkForceManagementTerminal, a request alarm confirmation may be requires set to true or false if a request alarm confirmation is needed bool no

steps[i].alarms.form If terminal type selected sendAlarmToWorkForceManagementTerminal set with trigger form name. string no

steps[i].alarms.formInterval Minimum form trigger interval int no

steps[i].alarms.warningATDBefore If set to true an alert is sent if departure happens earlier than the planned bool no

steps[i].alarms.warningATDBeforeDuration If warningATDBefore is set to true, this field define the time minus in minutes int no

steps[i].alarms.warningATDAfter If set to true an alert is sent if departure happens later than the planned bool no

steps[i].alarms.warningATDAfterDuration If warningATDAfter is set to true, this field define the time plus in minutes int no

steps[i].alarms.warningETABefore If set to true an alert is sent bool no

steps[i].alarms.warningETABeforeDuration If warningETABeforeDuration is set to true, this field define the time minus in minutes int no

steps[i].alarms.warningETAAfter If set to true an alert is sent if arrival happens later than the planned time bool no

steps[i].alarms.warningETAAfterDuration If warningETAAfter is set to true, this field define the time plus in minutes int no

steps[i].alarms.warningETATolerance If set to true an alert is sent once if estimated arrival time falls outside tolerance bool no

steps[i].alarms.warningETAAfterImidiately If warningETAAfter is set to true, set to true to received an imediate alert as soon the vehicle is late bool no

steps[i].alarms.warningATDAfterImidiately If warningETAAfterDuration is set to true, set to true to received an imediate alert as soon the vehicle is late bool no

steps[i].messages The information sent to driver. object no

steps[i].messages.message The message text to be sent to driver string no

steps[i].messages.scheduleArriveTime Send scheduled time of arrival. bool no false

steps[i].messages.destinationPoint Send the destination location bool no false

steps[i].messages.jobId The ID of the job, if any. If a jobId is specified, then it must correspond to an existing job int no

steps[i].messages.taskId The ID if the task, if any. If a taskId is specified, then it must correspond to an existing task int no

altDirIndex The index of a selected alternative path. int no 0

steps[i].dragPoints Array of points used to calculate route path object no

options Options used when requesting the directions route to the maps service object no

options.avoidHighways Avoid highways bool no true, false false

options.reorderingWaypointsAllowed Reorder waypoints to optimize route bool no true, false false

options.avoidTolls Avoid tolls bool no true, false false

options.avoidFerries Avoid ferries, if possible bool no true, false false

options.costOptimized Cover maximum distance using extra hours and reduced rest bool no true, false false

options.vehicleClassId The identifier of the vehicle class
int no

options.vehicleProfileId The ID of the profile of the vehicle.
The profile of the vehicle may be important the account is configured for using the Advanced routing with Here maps.
The list of vehicle profiles can be obtained using the endpoint Gets vehicle classes. int no

options.useDrivingTimeRestrictionsRules Use driving time restriction rules. bool no true, false true

options.useExistingVehicleDrivingTime Calculate using current driving time of driver(s) bool no true, false false

options.vehicleDrivingTimeId This field indicates the ID of the vehicle which driving times should be considered when calculating the route times of arrival and departure. If null, the driving times aren't applied. int no null

options.coverMaxDistance If set to true Cover maximum distance using extra hours and reduced rest. bool no true, false false

options.useTeamDrivers If set to true, use team drivers. bool no true, false false

options.useClientTimes Use step start and arrival planned times passed in the body. bool no true, false false

options.stepToleranceStartTimeBefore If set to a valid time, overrides the «Start Tolerance» > «Before Start Time» in the route account configuration.
If missing or invalid, falls back to the account configuration. time no "hh:mm" (from "00:00" to "23:59")

options.stepToleranceStartTimeAfter If set to a valid time, overrides the «Start Tolerance» > «After Start Time» in the route account configuration.
If missing or invalid, falls back to the account configuration. time no "hh:mm" (from "00:00" to "23:59")

field1 Any type of information of a vehicle string no

field2 Any type of information of a vehicle string no

field3 Any type of information of a vehicle string no

Note: The fields that are not mencioned in this list are not being used.

Response content

{
    "Id": 0
    "RouteExecutionId":
    {
        "Id": 0
    }
}

Field	Description
Id	The ID the route int
RouteExecutionId.Id	The ID of the created route execution int

Response HTTP Codes

201 - Created

The route was successfully assigned to the vehicle

204 - No content

400 - Bad Request

Route is null
Route.Steps is null or empty
Route.Name is null or empty
Route.Code is not null and length > 10
Route.Steps.corridorWidth width below 0.01
Route.Steps.PlaceId is invalid
Route.Steps.Coordinates are null
Route.Steps.Planned is null
Route.Notifications Time/Distance with delta null or below 0
Route.Notifications.Warmings is not null and emails or phones are null or invalid
Route.Notifications.Others is not null and emails or phones are null or invalid
Route.Alarms.Contacts is not null and emails or phones are null or invalid
Route.Messages is not null and JobId is different or above 0 and invalid
Route.Messages is not null and JobId different or above 0 and invalid
If an error ocurrs while obtaining data from the Directions Service
When not using polylines, if Starts or Arrival objects are not specified
If the Planned timestamp of a step's Start is before the Planned timestamp of the previous step's Arrival

401 - Unauthorized

Invalid credencials
If the user doesn't have permission to request a directcions route from the maps service

403 - Forbidden

If the authenticated user doesn t have permission to create/edit routes

404 - Not found

If the vehicleId is not related to user
If an error occurs when creating the polyline

409 - Conflict

If route for that vehicle is overlapping with another one
If the vehicles have WFM and Navigator associated.
If it was WFM and we come from multiple Jobs creating a single route
If the vehicle has a NAV device but passing both messages and jobs