Stop Event Schema

Type Aliases

StopWebhookData

Ƭ StopWebhookData: Object

The data that will be exported on all stop webhook events, i.e., those with type stop.*.

Example

{
  "id": "teams/deOCJ3JCXZhpKNCVAC7o/routes/gjaqksJIa26qGPzsgBXT/stops/rpX5zK2kRFlIfwREp1js",
  "plan": {
    "id": "zeOCJaJCzZhpKVCVAC9o",
    "title": "Tue, Nov 22 Route 1",
    "driverCount": 1
  },
  "route": {
    "id": "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": {
      "name": null,
      "email": "verygooddriver@getcircuit.com",
      "phoneNumber": null
    }
  },
  "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",
  "estimatedTimeAtStop": null,
  "notes": null,
  "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": {
    "eta": 1669153050,
    "earliestTime": 1669152050,
    "latestTime": 1669154050
  },
  "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	string	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 spreadsheets imports to force a specific stop in a plan to be distributed to a specific driver. Default null
estimatedTimeAtStop	number | null	Time that the driver estimate to spend on the stop to do his job (deliver a parcel, visit a client, etc) in seconds. A value only needs to be provided when overriding the user's preferences. Default null
notes	string | null	Notes for the delivery. Default null
orderInfo	OrderInfo | null	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 start: The first stop of the route. end: The last stop of the route. stop: Any other stop kind.
recipient	StopRecipient | null	The recipient of the delivery.
activity	StopActivity | null	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	PlanData | null	Information about the plan related to the route Default null
route	RouteData	Information about the route containing the stop.
eta	ETAData	Estimated time of arrival at the stop.
stopPosition	number	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

---

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. Default null
longitude	number | null	Longitude coordinate of the stop location. 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 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

---

RouteData

Ƭ RouteData: Object

Information about the route containging the stop.

Example

{
  "id": "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": {
    "name": null,
    "email": "verygooddriver@getcircuit.com",
    "phoneNumber": null
  }
}

Type declaration

Name	Type	Description
id	string	The unique identifier of the route.
title	string	The title of the route. Default ''
stopCount	number	Number of stops in the route. Default 0
state	RouteState | null	Current state of the route. Default null
driver	DriverData | null	The route driver.

---

RouteState

Ƭ RouteState: Object

The current state of the route when the event was generated.

Example

{
  "completed": false,
  "completedAt": null,
  "distributed": true,
  "distributedAt": 1669153050,
  "notifiedRecipients": false,
  "notifiedRecipientsAt": null,
  "started": false,
  "startedAt": null
}

Type declaration

Name	Type	Description
completed	boolean	If route is completed or not. Default false
completedAt	EpochTimestamp | null	Timestamp in seconds of when route was completed. Default null
distributed	boolean	If route was distributed or not. Default false
distributedAt	EpochTimestamp | null	Timestamp in seconds of when route was distributed. Default null
notifiedRecipients	boolean	Whether recipients were notified or not. Default false
notifiedRecipientsAt	EpochTimestamp | null	Timestamp in seconds of when recipients were notified. Default null
started	boolean	If driver started the route or not. Default false
startedAt	EpochTimestamp | null	Timestamp in seconds of when route was started by the driver. Default null

---

DriverData

Ƭ DriverData: Object

Data on the driver of the route

Example

{
  "name": "John Doe",
  "email": "john.doe@getcircuit.com",
  "phone": "+1 555 555 5555",
}

Type declaration

Name	Type	Description
name	string | null	Full user name, no length restrictions yet Default null
email	string | null	User email Default null
phoneNumber	string | null	Phone number in E.164 format Default null

---

PlanData

Ƭ PlanData: Object

Plan data related to the route of the stop

Example

{
 "id": "zeOCJaJCzZhpKVCVAC9o",
  "title": "plan_123",
  "driverCount": 5,
}

Type declaration

Name	Type	Description
id	string	The unique identifier of the plan.
title	string	Title of the plan.
driverCount	number	Number of drivers in the plan, the same as the number of routes created from the same plan. Default 0

---

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

{
  "eta": 1669153050,
  "earliestTime": 1669152050,
  "latestTime": 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
eta	number	The estimated time of arrival in seconds since epoch.
earliestTime	number	The estimated earliest possible window time of arrival in seconds since epoch.
latestTime	number	The estimated latest possible window time of arrival in seconds since epoch.

---

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

Name	Type
latitude	number
longitude	number