Version: v0.2b

Stop Schema

Model

Stop

Stop = object

The Stop data model. All stops in the API will have this format.

A stop is a location that a driver will visit. A stop will always be associated with a plan, and can be associated with a route. A stop can be associated with a route if it is part of a plan that has been optimized.

Example

{
  "id": "plans/zeOCJaJCzZhpKVCVAC9o/stops/rpX5zK2kRFlIfwREp1js",
  "plan": "plans/gjaqksJIa26qGPzsgBXT",
  "route": {
    "id": "routes/gjaqksJIa26qGPzsgBXT",
    "title": "Tue, Nov 22 Route 1",
    "stopCount": 28,
    "state": {
      "completed": false,
      "completedAt": null,
      "distributed": true,
      "distributedAt": 1669153050,
      "notifiedRecipients": false,
      "notifiedRecipientsAt": null,
      "started": false,
      "startedAt": null
    },
    "driver": "drivers/gjaqksJIa26qGPzsgBXT",
    "plan": "plans/gjaqksJIa26qGPzsgBXT"
  },
  "address": {
    "address": "Very nice St., 150 - Nice Neighbourhood, Campinas - SP, 130876, Brazil",
    "placeId": "1cda3f263368264eefbb",
    "latitude": -22.12345,
    "longitude": -47.12345,
    "placeTypes": [
      "street_address"
    ],
    "addressLineOne": "Very nice St., 150",
    "addressLineTwo": "Nice Neighbourhood, Campinas - SP, 130876, Brazil"
  },
  "barcodes": ["123456789"],
  "driverIdentifier": "driveremail@spoke.com",
  "estimatedTravelDuration": 654,
  "estimatedTravelDistance": 1234,
  "notes": null,
  "timing": {
    "estimatedAttemptDuration": 300,
    "earliestAttemptTime": {
      "hour": 8,
      "minute": 0,
    },
    "latestAttemptTime": {
      "hour": 10,
      "minute": 0,
    }
  },
  "orderInfo": {
    "products": ["Taco"],
    "sellerName": "Sam's Taco Truck",
    "sellerOrderId": "ON-2301",
    "sellerWebsite": "https://sams.taco"
  },
  "paymentOnDelivery": {
    "amount": 1000,
    "currency": "USD"
  },
  "packageCount": 5,
  "weight": {
     "amount": 15,
     "unit": "kilogram"
  },
  "placeInVehicle": null,
  "type": "stop",
  "activity": "delivery",
  "recipient": {
    "email": "alvena.schulist33@spoke.com",
    "externalId": "The recipient's ID on your system",
    "name": "Alvena Schulist",
    "phone": "+1-555-555-5555"
  },
  "deliveryInfo": {
    "state": "unattempted",
    "attempted": false,
    "photoUrls": [],
    "succeeded": false,
    "signeeName": null,
    "attemptedAt": null,
    "signatureUrl": null,
    "attemptedLocation": null,
    "recipientProvidedNotes": null,
    "driverProvidedInternalNotes": null,
    "driverProvidedRecipientNotes": null
  },
  "paymentOnDelivery": {
    "amount": 1000,
    "currency": "USD"
  },
  "proofOfAttemptRequirements": {
    "enabled": null
  },
  "packageLabel": null,
  "eta": {
    "estimatedAt": 1669153050,
    "estimatedEarliestAt": 1669152050,
    "estimatedLatestAt": 1669154050
  },
  "etaNullReason": null,
  "customProperties": {
    "6f6a65df-3ece-402c-9ff7-0b324e0c666f": "123456",
    "58eefa1b-35f5-4f3d-9c82-7a02415f8dd7": null
  },
  "stopPosition": 1,
  "trackingLink": "https://track.spoke.com/123456789",
  "webAppLink": "https://dispatch.spoke.com/view-route?routeId=gjaqksJIa26qGPzsgBXT&planId=gjaqksJIa26qGPzsgBXT&stopId=rpX5zK2kRFlIfwREp1js&startsAt=1670382000",
  "circuitClientId": "pjaqksJIa26qGPzsgBXT"
}

Properties

Property	Type	Description
`id`	`StopId`	The stop identifier.
`address`	`StopAddress`	Object containing the address of the stop.
`barcodes`	`string`[]	List of barcodes associated with the Stop Example `["123456789"]` Default `[]`
~~`driverIdentifier`~~	`string` \| `null`	Either email or phone of a driver. This information is provided in spreadsheet imports to force a specific stop in a plan to be assigned to a specific driver. Default `null` Deprecated prefer `allowedDriversIdentifiers`
`allowedDriversIdentifiers`	`string`[]	An array of driver identifiers. Either email or phone of a driver. This information is used to force a specific stop in a plan to be assigned only to specific drivers. If no drivers are listed here, the stop will be assigned to any driver. Default `[]`
`timing`	`TimingData`	Timing information for the stop
`estimatedTravelDuration`	`number` \| `null`	Estimated time that the driver will take to arrive at this stop from the previous stop in seconds. Default `null`
`estimatedTravelDistance`	`number` \| `null`	Estimated travel distance the driver will take to arrive at this stop from the previous stop in meters. Default `null`
`notes`	`string` \| `null`	Notes for the delivery. Default `null`
`orderInfo`	`OrderInfo`	Information of the order made by the recipient. Default `null`
`packageCount`	`number` \| `null`	Amount of packages to be delivered in the stop. Default `null`
`weight`	`PackageWeight` \| `null`	Weight of the packages in the stop. The unit will be defined by the team's capacity unit within the team's settings in Dispatch web UI. Default `null`
`placeInVehicle`	`PlaceInVehicle` \| `null`	The place where the package is in the vehicle of the driver. Default `null`
`type`	`"stop"` \| `"start"` \| `"end"`	The type of the stop. `start`: The first stop of the route. `end`: The last stop of the route. `stop`: Any other stop kind.
`recipient`	`StopRecipient`	The recipient of the delivery.
`activity`	`StopActivity`	The activity performed at the stop by the driver. Default `'delivery'`
`packageLabel`	`string` \| `null`	The package identifier used for drivers to identify the package associated with the stop. A number is uniquely generated by clients, but drivers can edit it as necessary. Default `null`
`deliveryInfo`	`DeliveryInfo` \| `null`	Information about the delivery of the package. Default `null`
`paymentOnDelivery`	`PaymentOnDelivery` \| `null`	Payment on delivery (also known as "Cash on Delivery") data for this stop.
`proofOfAttemptRequirements`	`ProofOfAttemptRequirements`	The requirements on the proof of attempt for this stop. This dictates whether or not the driver will be required to collect proof, be it a signature or a photo, when attempting the stop. Please notice that this will only be enforced if your team subscription allows collecting proof of attempt.
`plan`	`PlanId`	Information about the plan related to the stop
`route`	`Route` \| `null`	Information about the route related to the stop. See Route.
`optimizationOrder`	`"first"` \| `"last"` \| `"default"`	The preferred order of the stop after optimizing the route. `first`: The stop will be placed at the start of the route. `last`: The stop will be placed at the end of the route. `default`: The stop will be placed in an optimal position based on the route optimization algorithm. Default `'default'`
`eta`	`ETAData` \| `null`	Estimated time of arrival at the stop.
`etaNullReason`	`ETADataNullReason` \| `null`	Reason why the ETA was not provided.
`customProperties`	`Record`<`string`, `string` \| `null`> \| `null`	A map of custom properties associated with this stop. See CustomStopProperty.
`stopPosition`	`number` \| `null`	Stop position in the route. If the stop has the type 'start', it will be 0. All the 'stop' type stops will start at 1. The 'end' type stop will be the last position in the route. Note: This value is the position of the stop in the optimized route, if the driver completes stops in a different order, this field will not reflect that, if needed to order the stops by the actual delivery order when not following the optimized route, use the `DeliveryInfo.attemptedAt` field.
`trackingLink`	`string` \| `null`	Tracking link for this stop. Only available after the route is started and not available for 'start' and 'end' stops.
`webAppLink`	`string`	Link to the stop in Spoke Dispatch Web App
`circuitClientId`	`string` \| `null`	If set, the stop will be associated with the Spoke Connect with the given Client ID.

Identifier

StopId

StopId = `plans/${string}/stops/${string}`

A stop id is a string that is unique for a stop. It is used to identify the stop in the API.

Example

"plans/zeOCJaJCzZhpKVCVAC9o/stops/rpX5zK2kRFlIfwREp1js"

Fields

StopAddress

StopAddress = object

Data used to identify the stop location.

Example

{
  "address": "Very nice St., 150 - Nice Neighbourhood, Campinas - SP, 130876, Brazil",
  "placeId": "1cda3f263368264eefbb",
  "latitude": -22.12345,
  "longitude": -47.12345,
  "placeTypes": [
    "street_address"
  ],
  "addressLineOne": "Very nice St., 150",
  "addressLineTwo": "Nice Neighbourhood, Campinas - SP, 130876, Brazil"
},

Properties

Property	Type	Description
`address`	`string`	Combined address string. Default '' It will always be an empty string `''` if imported from a spreadsheet using latitude and longitude.
`addressLineOne`	`string`	First line of the address. Default `''`
`addressLineTwo`	`string`	Second line of the address. Default `''`
`latitude`	`number` \| `null`	Latitude coordinate of the stop location in decimal degrees. Default `null`
`longitude`	`number` \| `null`	Longitude coordinate of the stop location in decimal degrees. Default `null`
`placeId`	`string` \| `null`	The identifier of the Place corresponding to this stop on Google Places. Default `null`
`placeTypes`	`string`[]	Array of strings that is provided by the Google AutoCompleteAPI. Default `[]`

StopRecipient

StopRecipient = object

Information on the recipient of the package.

Example

{
  "email": "alvena.schulist33@spoke.com",
  "externalId": "The recipient's ID on your system",
  "name": "Alvena Schulist",
  "phone": "+1-555-555-5555"
}

Properties

Property	Type	Description
`email`	`string` \| `null`	Email address of recipient Default `null`
`externalId`	`string` \| `null`	Id of recipient in external system of the team's company Default `null`
`name`	`string` \| `null`	Full name of recipient Default `null`
`phone`	`string` \| `null`	Phone number of recipient Default `null`

DeliveryInfo

DeliveryInfo = object

Information about the delivery of the package.

Example

{
  "state": "delivered_to_recipient",
  "attempted": true,
  "photoUrls": [],
  "succeeded": true,
  "signeeName": "",
  "attemptedAt": 1669151179,
  "signatureUrl": null,
  "attemptedLocation": {
    "latitude": -3.1234,
    "longitude": -38.7654
  },
  "recipientProvidedNotes": null,
  "driverProvidedInternalNotes": "",
  "driverProvidedRecipientNotes": ""
}

Properties

Property	Type	Description
`attempted`	`boolean`	Default `false`
`attemptedAt`	`EpochTimestamp` \| `null`	Timestamp in seconds of when the driver attempted the delivery. Default `null`
`attemptedLocation`	`Location` \| `null`	The location this stop was attempted at Default `null`
`driverProvidedInternalNotes`	`string` \| `null`	Internal notes provided by the driver. Default `null`
`driverProvidedRecipientNotes`	`string` \| `null`	Recipient notes provided by the driver. Default `null`
`photoUrls`	`string`[]	URLs of proof of delivery photos taken and uploaded by the driver. The URLs here can return not found if the driver mobile app is still uploading the photos, but once the upload is complete, the URL will contain the image. Default `[]`
`recipientProvidedNotes`	`string` \| `null`	Notes provided by the recipient. Default `null`
`signatureUrl`	`string` \| `null`	URL of the recipient signature. The URL here can return not found if the driver mobile app is still uploading it, but once the upload is complete, the URL will contain the image. Default `null`
`signeeName`	`string` \| `null`	Signee name Default `null`
`state`	`DeliveryState`	Default `'unattempted'`
`succeeded`	`boolean`	If the delivery was successful. Default `false`

PaymentOnDelivery

PaymentOnDelivery = object

Payment on delivery (also known as "Cash on Delivery") data for this stop.

Example

{
  "amount": 599,
  "currency": "USD"
}

Properties

Property Type Description

Property	Type	Description
`amount`	`PriceInMinorUnits` \| `null`	The amount in minor units (e.g. cents) to be collected upon delivery. Example `599`
`currency`	`string`	The payment's currency in ISO 4217 standard. Example `'USD'`

amount

PriceInMinorUnits | null

The amount in minor units (e.g. cents) to be collected upon delivery.

Example

currency

string

The payment's currency in ISO 4217 standard.

Example

'USD'

ProofOfAttemptRequirements

ProofOfAttemptRequirements = object

Requirements on the proof of attempt for this stop.

This dictates whether or not the driver will be required to collect proof, be it a signature or a photo, when attempting the stop.

Please notice that this will only be enforced if your team subscription allows collecting proof of attempt.

Example

{
  "enabled": true
}

Properties

Property Type Description

Property	Type	Description
`enabled`	`boolean` \| `null`	Whether collecting the proof of attempt is enabled for this stop. Please notice that this will only be enforced if your team subscription allows collecting proof of attempt. If this is `null` it will use the default value for the team. Set explicitly to `false` to disable the proof of attempt collection for this stop. Set explicitly to `true` to enable the proof of attempt collection for this stop, following the policies of the team on each type of attempt. Default `null`

enabled

boolean | null

Whether collecting the proof of attempt is enabled for this stop.

Please notice that this will only be enforced if your team subscription allows collecting proof of attempt.

If this is null it will use the default value for the team.

Set explicitly to false to disable the proof of attempt collection for this stop.

Set explicitly to true to enable the proof of attempt collection for this stop, following the policies of the team on each type of attempt.

Default

null

OrderInfo

OrderInfo = object

Information of the order made by the recipient.

Example

{
  "products": ["Taco"],
  "sellerName": "Sam's Taco Truck",
  "sellerOrderId": "ON-2301",
  "sellerWebsite": "https://sams.taco"
}

Properties

Property	Type	Description
`products`	`string`[]	Name of the products to be delivered. Default [] To get the products to be split in this array, whether using the Web UI or submitting via a spreadsheet, use a `,` (comma) or a `;` (semicolon) as a delimiter between each product.
`sellerOrderId`	`string` \| `null`	The ID of the order created by the seller that is usually shared with the client. Default `null`
`sellerName`	`string` \| `null`	Name of the seller where the user bought the products. Default `null`
`sellerWebsite`	`string` \| `null`	Website where the user bought the products. Default `null`

PlaceInVehicle

PlaceInVehicle = object

Where in the vehicle the package was placed.

Example

{
 "x": "left",
 "y": "front",
 "z": "floor"
}

Properties

Property	Type	Description
`x`	`"left"` \| `"right"` \| `null`	Default `null`
`y`	`"front"` \| `"middle"` \| `"back"` \| `null`	Default `null`
`z`	`"floor"` \| `"shelf"` \| `null`	Default `null`

ETAData

ETAData = object

Estimated time of arrival at the stop.

It is important to note that this is not a guarantee that the driver will arrive at the stop at the specified time. It is only an estimate, especially if the driver has not started the route yet, as the estimated start time is then based on the expected start time of the route.

Example

{
  "estimatedAt": 1669153050,
  "estimatedEarliestAt": 1669152050,
  "estimatedLatestAt": 1669154050
}

Properties

Property	Type	Description
`estimatedArrivalAt`	`EpochTimestamp`	The estimated time of arrival in seconds since epoch.
`estimatedEarliestArrivalAt`	`EpochTimestamp`	The estimated earliest possible window time of arrival in seconds since epoch.
`estimatedLatestArrivalAt`	`EpochTimestamp`	The estimated latest possible window time of arrival in seconds since epoch.

ETADataNullReason

ETADataNullReason = object

Contains the reason why the ETA was not provided.

This will be used to explain why the ETA was not provided for the stop.

Example

{
  "reason": "not_optimized",
  "message": "The stop has not been optimized yet."
}

Properties

Property Type Description

Property	Type	Description
`reason`	`"not_optimized"` \| `"subscription_not_supported"`	Reason for the null ETA. `not_optimized`: The stop has not been optimized yet. `subscription_not_supported`: The team subscription does not support ETAs.
`message`	`string`	Human readable message explaining the reason for the null ETA.
`url`	`string` \| `null`	URL to a help article explaining the reason for the null ETA.

reason

"not_optimized" | "subscription_not_supported"

Reason for the null ETA.

not_optimized: The stop has not been optimized yet.
subscription_not_supported: The team subscription does not support ETAs.

message

string

Human readable message explaining the reason for the null ETA.

url

string | null

URL to a help article explaining the reason for the null ETA.

TimingData

TimingData = object

Timing information for the stop.

The timing information for the stop. This will be used to calculate the optimal time to visit the stop.

Example

{
 "earliestAttemptTime": {
   "hour": 8,
   "minute": 0
 },
 "latestAttemptTime": {
   "hour": 10,
   "minute": 0
 },
 "estimatedAttemptDuration": 300
}

Properties

Property Type Description

Property	Type	Description
`earliestAttemptTime`	`TimeOfDay` \| `null`	Earliest attempt time this stop should occur at. Default `null`
`latestAttemptTime`	`TimeOfDay` \| `null`	Latest attempt time this stop should occur at. Default `null`
`estimatedAttemptDuration`	`number` \| `null`	Time that the driver estimates to spend on the stop to do his job (deliver a parcel, visit a client, etc) in seconds. This will only be set if this was overidden for this stop, otherwise this will be null and all the calculations will use the default team value. Default `null`

earliestAttemptTime

TimeOfDay | null

Earliest attempt time this stop should occur at.

Default

null

latestAttemptTime

TimeOfDay | null

Latest attempt time this stop should occur at.

Default

null

estimatedAttemptDuration

number | null

Time that the driver estimates to spend on the stop to do his job (deliver a parcel, visit a client, etc) in seconds. This will only be set if this was overidden for this stop, otherwise this will be null and all the calculations will use the default team value.

Default

null

TimeOfDay

TimeOfDay = object

The time of day in hours and minutes.

Example

{
  "hour": 8,
  "minute": 0
}

Properties

Property	Type	Description
`hour`	`number`	The hour of the day in 24-hour format.
`minute`	`number`	The minute of the hour.

DeliveryState

DeliveryState = "delivered_to_recipient" | "delivered_to_third_party" | "delivered_to_mailbox" | "delivered_to_safe_place" | "delivered_to_pickup_point" | "delivered_other" | "picked_up_from_customer" | "picked_up_unmanned" | "picked_up_from_locker" | "picked_up_other" | "failed_not_home" | "failed_cant_find_address" | "failed_no_parking" | "failed_no_time" | "failed_package_not_available" | "failed_missing_required_proof" | "failed_payment_not_received" | "failed_other" | "unattempted"

The current delivery state when this event is emitted.

unattempted: The delivery has not been attempted yet.
delivered_to_recipient: The delivery was successfully delivered to the recipient.
delivered_to_third_party: The delivery was successfully delivered to a third party.
delivered_to_mailbox: The delivery was successfully delivered to a mailbox.
delivered_to_safe_place: The delivery was successfully delivered to a safe place.
delivered_to_pickup_point: The delivery was successfully delivered to a pickup point.
delivered_other: The delivery was successfully delivered with an unknown method.
picked_up_from_customer: The delivery was successfully picked up from the customer.
picked_up_unmanned: The delivery was successfully picked up without interaction with the customer.
picked_up_from_locker: The delivery was successfully picked up from a locker.
picked_up_other: The delivery was successfully picked up with an unknown method.
failed_not_home: The delivery failed because the recipient was not at home.
failed_cant_find_address: The delivery failed because the address could not be found.
failed_no_parking: The delivery failed because there was no parking space available.
failed_no_time: The delivery failed because the driver did not have enough time to complete the delivery.
failed_package_not_available: The delivery failed because the package was not available on the truck.
failed_missing_required_proof: The delivery failed because the driver did not collect the required proof of delivery.
failed_payment_not_received: The delivery failed because the driver did not collect the payment.
failed_other: The delivery failed for an unknown reason.

StopActivity

StopActivity = "delivery" | "pickup"

The activity performed at the stop by the driver.

delivery: The driver has to deliver the package
pickup: The driver has to pick up the package

Location

Location = object

A location object with latitude and longitude.

Example

{
  "latitude": -22.12345,
  "longitude": -47.12345
}

Properties

Property	Type
`latitude`	`number`
`longitude`	`number`

PackageWeight

PackageWeight = object

Package weight at the stop.

Example

{
  "amount": 15,
  "unit": "kilogram"
}

Properties

Property	Type
`amount`	`LoadAmount`
`unit`	`DisplayLoadUnit`

Model​

Stop​

Example​

Properties​

Identifier​

StopId​

Example​

Fields​

StopAddress​

Example​

Properties​

StopRecipient​

Example​

Properties​

DeliveryInfo​

Example​

Properties​

PaymentOnDelivery​

Example​

Properties​

ProofOfAttemptRequirements​

Example​

Properties​

OrderInfo​

Example​

Properties​

PlaceInVehicle​

Example​

Properties​

ETAData​

Example​

Properties​

ETADataNullReason​

Example​

Properties​

TimingData​

Example​

Properties​

TimeOfDay​

Example​

Properties​

DeliveryState​

StopActivity​

Location​

Example​

Properties​

PackageWeight​

Example​

Properties​

Model

Stop

Example

Properties

Identifier

StopId

Example

Fields

StopAddress

Example

Properties

StopRecipient

Example

Properties

DeliveryInfo

Example

Properties

PaymentOnDelivery

Example

Properties

ProofOfAttemptRequirements

Example

Properties

OrderInfo

Example

Properties

PlaceInVehicle

Example

Properties

ETAData

Example

Properties

ETADataNullReason

Example

Properties

TimingData

Example

Properties

TimeOfDay

Example

Properties

DeliveryState

StopActivity

Location

Example

Properties

PackageWeight

Example

Properties