Skip to main content
Version: v0.2b

Stop Schema

Type Aliases

Stop

Ƭ Stop: Object

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

Description

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.

Notice that you cannot edit a stop after it has been optimized or distributed in the current version of the API. You can, however, edit a stop before it has been optimized or distributed. You can also edit a stop after it has been optimized or distributed if you are using the Web UI.

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"
},
"driverIdentifier": "driveremail@getcircuit.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"
},
"packageCount": 5,
"placeInVehicle": null,
"type": "stop",
"activity": "delivery",
"recipient": {
"email": "alvena.schulist33@getcircuit.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
},
"packageLabel": null,
"eta": {
"estimatedAt": 1669153050,
"estimatedEarliestAt": 1669152050,
"estimatedLatestAt": 1669154050
},
"etaNullReason": null,
"stopPosition": 1,
"trackingLink": "https://track.getcircuit.com/123456789",
"webAppLink": "https://team.getcircuit.com/view-route?routeId=gjaqksJIa26qGPzsgBXT&planId=gjaqksJIa26qGPzsgBXT&stopId=rpX5zK2kRFlIfwREp1js&startsAt=1670382000",
"circuitClientId": "pjaqksJIa26qGPzsgBXT"
}

Type declaration

NameTypeDescription
idStopIdThe stop identifier.
addressStopAddressObject containing the address of the stop.
driverIdentifierstring | nullEither 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
allowedDriversIdentifiersstring[]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 []
timingTimingDataTiming information for the stop
estimatedTravelDurationnumber | nullEstimated time that the driver will take to arrive at this stop from the previous stop in seconds. Default null
estimatedTravelDistancenumber | nullEstimated travel distance the driver will take to arrive at this stop from the previous stop in meters. Default null
notesstring | nullNotes for the delivery. Default null
orderInfoOrderInfoInformation of the order made by the recipient. Default null
packageCountnumber | nullAmount of packages to be delivered in the stop. Default null
placeInVehiclePlaceInVehicle | nullThe place where the package is in the vehicle of the driver. Default null
type"stop" | "start" | "end"The type of the stop. Description
  • start: The first stop of the route.
  • end: The last stop of the route.
  • stop: Any other stop kind.
recipientStopRecipientThe recipient of the delivery.
activityStopActivityThe activity performed at the stop by the driver. Default 'delivery'
packageLabelstring | nullThe 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
deliveryInfoDeliveryInfo | nullInformation about the delivery of the package. Default null
planPlanIdInformation about the plan related to the stop
routeRoute | nullInformation about the route related to the stop. See Route
optimizationOrder"first" | "last" | "default"The preferred order of the stop after optimizing the route. Description
  • 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'
etaETAData | nullEstimated time of arrival at the stop.
etaNullReasonETADataNullReason | nullReason why the ETA was not provided.
stopPositionnumber | nullStop 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.
trackingLinkstring | nullTracking link for this stop. Only available after the route is started and not available for 'start' and 'end' stops.
webAppLinkstringLink to the stop in Circuit For Teams Web App
circuitClientIdstring | nullIf set, the stop will be associated with the Circuit Client Portal with the given Client ID.

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"

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"
},

Type declaration

NameTypeDescription
addressstringCombined address string. Default '' Description It will always be an empty string '' if imported from a spreadsheet using latitude and longitude.
addressLineOnestringFirst line of the address. Default ''
addressLineTwostringSecond line of the address. Default ''
latitudenumber | nullLatitude coordinate of the stop location in decimal degrees. Default null
longitudenumber | nullLongitude coordinate of the stop location in decimal degrees. Default null
placeIdstring | nullThe identifier of the Place corresponding to this stop on Google Places. Default null
placeTypesstring[]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@getcircuit.com",
"externalId": "The recipient's ID on your system",
"name": "Alvena Schulist",
"phone": "+1-555-555-5555"
}

Type declaration

NameTypeDescription
emailstring | nullEmail address of recipient Default null
externalIdstring | nullId of recipient in external system of the team's company Default null
namestring | nullFull name of recipient Default null
phonestring | nullPhone 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": ""
}

Type declaration

NameTypeDescription
attemptedbooleanDefault false
attemptedAtEpochTimestamp | nullTimestamp in seconds of when the driver attempted the delivery. Default null
attemptedLocationLocation | nullThe location this stop was attempted at Default null
driverProvidedInternalNotesstring | nullInternal notes provided by the driver. Default null
driverProvidedRecipientNotesstring | nullRecipient notes provided by the driver. Default null
photoUrlsstring[]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 []
recipientProvidedNotesstring | nullNotes provided by the recipient. Default null
signatureUrlstring | nullURL 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
signeeNamestring | nullSignee name Default null
stateDeliveryStateDefault 'unattempted'
succeededbooleanIf the delivery was successful. Default false

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"
}

Type declaration

NameTypeDescription
productsstring[]Name of the products to be delivered. Default [] Description 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.
sellerOrderIdstring | nullThe ID of the order created by the seller that is usually shared with the client. Default null
sellerNamestring | nullName of the seller where the user bought the products. Default null
sellerWebsitestring | nullWebsite where the user bought the products. Default null

PlaceInVehicle

Ƭ PlaceInVehicle: Object

Where in the vehicle the package was placed.

Type declaration

NameTypeDescription
x"left" | "right" | nullDefault null
y"front" | "middle" | "back" | nullDefault null
z"floor" | "shelf" | nullDefault null

ETAData

Ƭ ETAData: Object

Estimated time of arrival at the stop.

Example

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

Description

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.

Type declaration

NameTypeDescription
estimatedArrivalAtEpochTimestampThe estimated time of arrival in seconds since epoch.
estimatedEarliestArrivalAtEpochTimestampThe estimated earliest possible window time of arrival in seconds since epoch.
estimatedLatestArrivalAtEpochTimestampThe estimated latest possible window time of arrival in seconds since epoch.

ETADataNullReason

Ƭ ETADataNullReason: Object

Type declaration

NameTypeDescription
reason"not_optimized" | "subscription_not_supported"Reason for the null ETA. Description
  • not_optimized: The stop has not been optimized yet.
  • subscription_not_supported: The team subscription does not support ETAs.
messagestringHuman readable message explaining the reason for the null ETA.
urlstring | nullURL to a help article explaining the reason for the null ETA.

TimingData

Ƭ TimingData: Object

Type declaration

NameTypeDescription
earliestAttemptTimeTimeOfDay | nullEarliest attemp time this stop should occur at. Default null
latestAttemptTimeTimeOfDay | nullLatest attemp time this stop should occur at. Default null
estimatedAttemptDurationnumber | nullTime 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

Type declaration

NameType
hournumber
minutenumber

DeliveryState

Ƭ DeliveryState: "delivered_to_recipient" | "delivered_to_third_party" | "delivered_to_mailbox" | "delivered_to_safe_place" | "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_other" | "unattempted"

The current delivery state when this event is emitted.

Description

  • 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_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_other: The delivery failed for an unknown reason.

StopActivity

Ƭ StopActivity: "delivery" | "pickup"

The activity performed at the stop by the driver.

Description

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

Location

Ƭ Location: Object

Type declaration

NameType
latitudenumber
longitudenumber