--- title: "Create a route" method: POST path: "/fleet/routes" tags: ["Routes"] --- # Create a route `POST /fleet/routes` ## Request - Base URL: `https://api.samsara.com` - URL: `https://api.samsara.com/fleet/routes` - Auth: HTTP bearer Create a route. The legacy version of this endpoint can be found at [samsara.com/api-legacy](https://www.samsara.com/api-legacy#operation/createDispatchRoute). Rate limit: 100 requests/min (learn more about rate limits here). To use this endpoint, select **Write Routes** under the Driver Workflow category when creating or editing an API token. Learn More. **Submit Feedback**: Likes, dislikes, and API feature requests should be filed as feedback in our API feedback form. If you encountered an issue or noticed inaccuracies in the API documentation, please submit a case to our support team. ## Request body - RoutesCreateRouteRequestBody - `driverId` string: ID of the driver. Can be either a unique Samsara ID or an [external ID](https://developers.samsara.com/docs/external-ids) for the driver. - `externalIds` object: A map of external ids - `name` string, required: Name for the route - `notes` string: Notes about the route. - `recomputeScheduledTimes` boolean: This optional boolean parameter controls whether route schedule arrival and departure times are recalculated. When set to true, the system will automatically recompute the scheduledArrivalTime and scheduledDepartureTime for each stop along the route during route creation. This process overrides any manually provided values, with the exception of the first stop, which retains its user-defined schedule. - `settings` RouteSettingsRequestBody: An optional dictionary, only necessary to override the defaults for route start and end conditions. - `routeCompletionCondition` 'arriveLastStop' | 'departLastStop': Defaults to 'arriveLastStop' which ends the route upon arriving at the final stop. The condition 'departLastStop' ends the route upon departing the last stop. If 'arriveLastStop' is set, then the departure time of the final stop should not be set. Valid values: `arriveLastStop`, `departLastStop` - `routeStartingCondition` 'departFirstStop' | 'arriveFirstStop': Defaults to 'departFirstStop' which starts the route upon departing the first stop in the route. The condition 'arriveFirstStop' starts the route upon arriving at the first stop in the route. If 'departFirstStop' is set, the arrival time of the first stop should not be set. Valid values: `departFirstStop`, `arriveFirstStop` - `sequencingMethod` 'unknown' | 'scheduledArrivalTime' | 'manual': Determines how stops are sequenced on the route. 'scheduledArrivalTime' sequences stops by their scheduled arrival times (default). 'manual' allows custom sequencing via stop.sequenceNumber. 'unknown' indicates the method is not specified. Valid values: `unknown`, `scheduledArrivalTime`, `manual` - `stops` CreateRouteStopWithOrdersRequestObjectRequestBody[], required: List of stops along the route. For each stop, exactly one of `addressId` and `singleUseLocation` are required. Depending on the `settings` on your route, either a `scheduledArrivalTime` or `scheduledDepartureTime` must be specified for the first job. - `addressId` string: ID of the address. An address [externalId](https://developers.samsara.com/docs/external-ids#using-external-ids) can also be used interchangeably here. - `appointmentWindows` RouteStopAppointmentWindowRequestBody[]: Appointment windows for the stop. - `endTime` string, required: The end time of the appointment window for the stop in RFC 3339 format. - `startTime` string, required: The start time of the appointment window for the stop in RFC 3339 format. - `externalIds` object: A map of external ids - `forms` RouteStopFormRequestObjectRequestBody[]: Form attachments for the stop. - `formTemplateId` string, uuid, required: ID of the form template to attach to the stop. - `isRequired` boolean: Whether the driver must complete the form before departing the stop. - `name` string: Name of the stop - `notes` string: Notes for the stop - `ontimeWindowAfterArrivalMs` integer: Specifies the time window (in milliseconds) after a stop's scheduled arrival time during which the stop is considered 'on-time'. - `ontimeWindowBeforeArrivalMs` integer: Specifies the time window (in milliseconds) before a stop's scheduled arrival time during which the stop is considered 'on-time'. - `orders` RouteStopOrderUpsertInputRequestBody[]: Orders to upsert and attach to this stop. - `customerProperties` FleetOrderCustomerPropertyObjectRequestBody[]: Order-specific customer metadata. - `key` string, required: Customer-defined property key. - `value` string, required: Customer-defined property value. - `externalIds` object: Org-scoped external identifiers. - `id` string: Existing Samsara order UUID. Required unless externalIds is supplied. - `samsaraCustomerOrderName` string: Human-readable order label. - `tasks` FleetOrderTaskUpsertInputRequestBody[], required: Tasks to upsert and attach to the containing stop. - `customerProperties` FleetOrderCustomerPropertyObjectRequestBody[]: Task-specific customer metadata. - `key` string, required: Customer-defined property key. - `value` string, required: Customer-defined property value. - `dispatcherNotes` string: Dispatcher-visible note. - `driverNotes` string: Driver-visible note. - `hubId` string: Hub UUID for this task. Nested route writes derive it from route context when omitted. - `id` string: Existing task ID. Omit to create a task. - `positionConstraintType` 'none' | 'first' | 'last': Task position constraint. Valid values: `none`, `first`, `last` - `quantities` FleetOrderQuantityInputRequestBody[]: Task quantities. - `capacityId` string: Optional capacity UUID for the task hub. - `label` string, required: Human-readable quantity label. - `value` number, required: Finite, non-negative quantity value. - `serviceDurationSeconds` integer: Expected service duration in seconds. - `serviceLocation` FleetOrderServiceLocationInputRequestBody: Saved or one-time service location for an order task. - `addressId` string: Saved address ID. Required for savedAddress locations. - `customAddress` FleetOrderCustomAddressInputRequestBody: A one-time structured service address. - `addressLine1` string: First address line. - `addressLine2` string: Second address line. - `city` string: City. - `country` string: Country. - `formattedAddress` string: Human-readable formatted address. - `latitude` number: Latitude in decimal degrees. - `longitude` number: Longitude in decimal degrees. - `postalCode` string: Postal code. - `state` string: State, province, or region. - `serviceLocationType` 'savedAddress' | 'customAddress', required: Location discriminator. Valid values: `savedAddress`, `customAddress` - `serviceWindowIdsToRemove` string[]: Existing service window UUIDs to retire. - `serviceWindows` FleetOrderServiceWindowUpsertInputRequestBody[]: Service windows to create or update. - `endTime` string, date-time: Service window end in RFC 3339 format. - `id` string: Existing service window UUID. Omit to create a window. - `startTime` string, date-time: Service window start in RFC 3339 format. - `taskType` 'delivery' | 'pickup' | 'pickupDelivery', required: Task type. Valid values: `delivery`, `pickup`, `pickupDelivery` - `scheduledArrivalTime` string, date-time: This is a required field for all stops EXCEPT the start and end, based on route start and stop settings selected. - `scheduledDepartureTime` string, date-time: This is a required field for all stops EXCEPT the start and end, based on route start and stop settings selected. - `sequenceNumber` integer: Manual sequence position for this stop. Only meaningful when route.settings.sequencingMethod=manual. Must be unique and positive when specified. - `singleUseLocation` RoutesSingleUseAddressObjectRequestBody: This field is used to indicate stops along the route for which an address has not been persisted. This field is mutually exclusive with addressId. - `address` string: Address of the stop. - `latitude` number, double, required: The latitude of the location - `longitude` number, double, required: The longitude of the location - `radiusMeters` number: The radius in meters for the geofence around this location. Must be a positive value. - `tagIds` string[]: An array of IDs of tags to associate with this route. - `vehicleId` string: ID of the vehicle. Can be either a unique Samsara ID or an [external ID](https://developers.samsara.com/docs/external-ids) for the vehicle. ## Response `200` OK response. - RoutesCreateRouteResponseBody - `data` BaseRouteWithOrdersResponseObjectResponseBody - `actualRouteEndTime` string, date-time: Actual end time, if it exists, for the route in RFC 3339 format. - `actualRouteStartTime` string, date-time: Actual start time, if it exists, for the route in RFC 3339 format. - `driver` GoaDriverTinyResponseResponseBody: A minified driver object. This object is only returned if the route is assigned to the driver. - `externalIds` object: A map of external ids - `id` string, required: ID of the driver - `name` string: Name of the driver - `externalIds` object: A map of external ids - `id` string, required: ID of the route - `name` string: Route name - `notes` string: Notes for the route - `orgLocalTimezone` string: The local timezone, as defined in Settings for your organization. Timezones use [IANA timezone database](https://www.iana.org/time-zones) keys (e.g. `America/Los_Angeles`, `America/New_York`, `Europe/London`, etc.). You can find a mapping of common timezone formats to IANA timezone keys [here](https://unicode.org/cldr/charts/latest/supplemental/zone_tzid.html). - `recurringRouteLiveSharingLinks` LiveSharingLinkResponseObjectResponseBody[]: List of shareable, non-expired 'By recurring Route' Live Sharing Links. - `expiresAtTime` string: Date that this link expires, in RFC 3339 format. - `liveSharingUrl` string, required: The shareable URL of the vehicle's location. - `name` string, required: Name of the Live Sharing Link. - `scheduledRouteEndTime` string, date-time: Scheduled end time, if it exists, for the route in RFC 3339 format. - `scheduledRouteStartTime` string, date-time: Scheduled start time, if it exists, for the route in RFC 3339 format. - `settings` RouteSettingsResponseBody: An optional dictionary, only necessary to override the defaults for route start and end conditions. - `routeCompletionCondition` 'arriveLastStop' | 'departLastStop': Defaults to 'arriveLastStop' which ends the route upon arriving at the final stop. The condition 'departLastStop' ends the route upon departing the last stop. If 'arriveLastStop' is set, then the departure time of the final stop should not be set. Valid values: `arriveLastStop`, `departLastStop` - `routeStartingCondition` 'departFirstStop' | 'arriveFirstStop': Defaults to 'departFirstStop' which starts the route upon departing the first stop in the route. The condition 'arriveFirstStop' starts the route upon arriving at the first stop in the route. If 'departFirstStop' is set, the arrival time of the first stop should not be set. Valid values: `departFirstStop`, `arriveFirstStop` - `sequencingMethod` 'unknown' | 'scheduledArrivalTime' | 'manual': Determines how stops are sequenced on the route. 'scheduledArrivalTime' sequences stops by their scheduled arrival times (default). 'manual' allows custom sequencing via stop.sequenceNumber. 'unknown' indicates the method is not specified. Valid values: `unknown`, `scheduledArrivalTime`, `manual` - `stops` RouteStopWithOrdersResponseObjectResponseBody[]: List of stops along the route - `actualArrivalTime` string, date-time: Actual arrival time, if it exists, for the route stop in RFC 3339 format. - `actualDepartureTime` string, date-time: Actual departure time, if it exists, for the route stop in RFC 3339 format. - `actualDistanceMeters` integer: Actual GPS-measured distance traveled from the previous stop's departure to this stop's arrival, in meters. Null for the first stop, skipped stops, or if GPS data is unavailable. - `address` GoaAddressTinyResponseResponseBody: A minified Address object - `externalIds` object: A map of external ids - `id` string, required: Id of the address - `name` string, required: Name of the address - `appointmentWindows` RouteStopAppointmentWindowResponseBody[]: Appointment windows for the stop. - `endTime` string, required: The end time of the appointment window for the stop in RFC 3339 format. - `startTime` string, required: The start time of the appointment window for the stop in RFC 3339 format. - `documents` GoaDocumentTinyResponseResponseBody[]: List of documents associated with the stop. - `id` string, required: Id of the document - `name` string: Name of the document - `enRouteTime` string, date-time: The time the stop became en-route, in RFC 3339 format. - `eta` string, date-time: Estimated time of arrival, if this stop is currently en-route, in RFC 3339 format. - `externalIds` object: A map of external ids - `forms` RouteStopFormResponseObjectResponseBody[]: List of forms associated with the stop. - `formTemplateId` string, uuid: ID of the form template. - `id` string, required: ID of the form submission. - `isRequired` boolean: Whether the driver must complete the form before departing the stop. - `id` string, required: Id of the stop - `issues` GoaIssueTinyResponseResponseBody[]: List of issues associated with the stop. - `id` string, required: ID of the issue - `liveSharingUrl` string: The shareable url of the stop's current status. - `locationLiveSharingLinks` LiveSharingLinkResponseObjectResponseBody[]: List of shareable, non-expired 'By Location' Live Sharing Links. - `expiresAtTime` string: Date that this link expires, in RFC 3339 format. - `liveSharingUrl` string, required: The shareable URL of the vehicle's location. - `name` string, required: Name of the Live Sharing Link. - `name` string, required: Name of the stop - `notes` string: Notes for the stop - `ontimeWindowAfterArrivalMs` integer: Specifies the time window (in milliseconds) after a stop's scheduled arrival time during which the stop is considered 'on-time'. - `ontimeWindowBeforeArrivalMs` integer: Specifies the time window (in milliseconds) before a stop's scheduled arrival time during which the stop is considered 'on-time'. - `orders` RouteStopOrderTaskReferenceObjectResponseBody[], required: Canonical order tasks attached to this stop. - `id` string, required: Samsara-generated canonical order UUID. - `taskId` string, required: Order task ID attached to this stop. - `plannedDistanceMeters` integer: Planned driving distance from the previous stop in meters. Based on routing calculations at route creation time. Null for the first stop or if routing data is unavailable. - `scheduledArrivalTime` string, date-time: Scheduled arrival time, if it exists, for the stop in RFC 3339 format. - `scheduledDepartureTime` string, date-time: Scheduled departure time, if it exists, for the stop in RFC 3339 format. - `sequenceNumber` integer: Manual sequence position of this stop. Only used when route.settings.sequencingMethod=manual. - `singleUseLocation` RoutesSingleUseAddressObjectResponseBody: This field is used to indicate stops along the route for which an address has not been persisted. This field is mutually exclusive with addressId. - `address` string: Address of the stop. - `latitude` number, double, required: The latitude of the location - `longitude` number, double, required: The longitude of the location - `radiusMeters` number: The radius in meters for the geofence around this location. Must be a positive value. - `skippedTime` string, date-time: Skipped time, if it exists, for the route stop in RFC 3339 format. - `state` 'unassigned' | 'scheduled' | 'en route' | 'skipped' | 'arrived' | 'departed', required: The current state of the route stop. Valid values: `unassigned`, `scheduled`, `en route`, `skipped`, `arrived`, `departed` - `tagIds` string[]: An array of IDs of tags to associate with this route. - `vehicle` GoaVehicleTinyResponseResponseBody: A minified vehicle object. This object is only returned if the route is assigned to the vehicle. - `externalIds` object: A map of external ids - `id` string: ID of the vehicle - `name` string: Name of the vehicle ## Other responses - `401`: Unauthorized response. - `404`: Not Found response. - `405`: Method Not Allowed response. - `413`: Content Too Large response. - `429`: Too Many Requests response. - `500`: Internal Server Error response. - `501`: Not Implemented response. - `502`: Bad Gateway response. - `503`: Service Unavailable response. - `504`: Gateway Timeout response. - `default`: Bad Request response. --- [API](https://skmtc.dev/samsara/apis/samsara-api.md) - [All operations](https://skmtc.dev/samsara/apis/samsara-api/llms.txt) - [OpenAPI document](https://skmtc.dev/samsara/apis/samsara-api/revisions/a9e35d4999be?raw)