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"
}
Type declaration
Name | Type | Description |
---|---|---|
id | StopId | The stop identifier. |
address | StopAddress | Object containing the address of the stop. |
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 |
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 |
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. Description
|
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 |
plan | PlanId | Information about the plan related to the stop |
route | Route | null | Information about the route related to the stop. See Route |
eta | ETAData | null | Estimated time of arrival at the stop. |
etaNullReason | ETADataNullReason | null | Reason why the ETA was not provided. |
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 Circuit For Teams Web App |
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
Name | Type | Description |
---|---|---|
address | string | Combined address string. Default '' Description 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@getcircuit.com",
"externalId": "The recipient's ID on your system",
"name": "Alvena Schulist",
"phone": "+1-555-555-5555"
}
Type declaration
Name | 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": ""
}
Type declaration
Name | 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 |
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
Name | Type | Description |
---|---|---|
products | string [] | 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. |
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.
Type declaration
Name | 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.
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
Name | 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
Type declaration
Name | Type | Description |
---|---|---|
reason | "not_optimized" | "subscription_not_supported" | Reason for the null ETA. Description
|
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
Type declaration
Name | Type | Description |
---|---|---|
earliestAttemptTime | TimeOfDay | null | Earliest attemp time this stop should occur at. Default null |
latestAttemptTime | TimeOfDay | null | Latest attemp 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
Type declaration
Name | Type |
---|---|
hour | number |
minute | number |
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 packagepickup
: The driver has to pick up the package
Location
Ƭ Location: Object
Type declaration
Name | Type |
---|---|
latitude | number |
longitude | number |