Version: v0.2b

Stop Schema

Model

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.

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

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` `ts 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` `ts []`
`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` `ts null`
`estimatedTravelDistance`	`number` \| `null`	Estimated travel distance the driver will take to arrive at this stop from the previous stop in meters. `Default` `ts null`
`notes`	`string` \| `null`	Notes for the delivery. `Default` `ts null`
`orderInfo`	`OrderInfo`	Information of the order made by the recipient. `Default` `ts null`
`packageCount`	`number` \| `null`	Amount of packages to be delivered in the stop. `Default` `ts null`
`placeInVehicle`	`PlaceInVehicle` \| `null`	The place where the package is in the vehicle of the driver. `Default` `ts 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`	The recipient of the delivery.
`activity`	`StopActivity`	The activity performed at the stop by the driver. `Default` `ts '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` `ts null`
`deliveryInfo`	`DeliveryInfo` \| `null`	Information about the delivery of the package. `Default` `ts null`
`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. `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` `ts 'default'`
`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
`circuitClientId`	`string` \| `null`	If set, the stop will be associated with the Circuit Client Portal 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"
},

Type declaration

Name	Type	Description
`address`	`string`	Combined address string. `Default` `ts ''` `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` `ts ''`
`addressLineTwo`	`string`	Second line of the address. `Default` `ts ''`
`latitude`	`number` \| `null`	Latitude coordinate of the stop location in decimal degrees. `Default` `ts null`
`longitude`	`number` \| `null`	Longitude coordinate of the stop location in decimal degrees. `Default` `ts null`
`placeId`	`string` \| `null`	The identifier of the Place corresponding to this stop on Google Places. `Default` `ts null`
`placeTypes`	`string`[]	Array of strings that is provided by the Google AutoCompleteAPI. `Default` `ts []`

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` `ts null`
`externalId`	`string` \| `null`	Id of recipient in external system of the team's company `Default` `ts null`
`name`	`string` \| `null`	Full name of recipient `Default` `ts null`
`phone`	`string` \| `null`	Phone number of recipient `Default` `ts 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` `ts false`
`attemptedAt`	`EpochTimestamp` \| `null`	Timestamp in seconds of when the driver attempted the delivery. `Default` `ts null`
`attemptedLocation`	`Location` \| `null`	The location this stop was attempted at `Default` `ts null`
`driverProvidedInternalNotes`	`string` \| `null`	Internal notes provided by the driver. `Default` `ts null`
`driverProvidedRecipientNotes`	`string` \| `null`	Recipient notes provided by the driver. `Default` `ts 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` `ts []`
`recipientProvidedNotes`	`string` \| `null`	Notes provided by the recipient. `Default` `ts 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` `ts null`
`signeeName`	`string` \| `null`	Signee name `Default` `ts null`
`state`	`DeliveryState`	`Default` `ts 'unattempted'`
`succeeded`	`boolean`	If the delivery was successful. `Default` `ts 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` `ts []` `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` `ts null`
`sellerName`	`string` \| `null`	Name of the seller where the user bought the products. `Default` `ts null`
`sellerWebsite`	`string` \| `null`	Website where the user bought the products. `Default` `ts null`

PlaceInVehicle

Ƭ PlaceInVehicle: Object

Where in the vehicle the package was placed.

Example

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

Type declaration

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

ETAData

Ƭ ETAData: Object

Estimated time of arrival at the stop.

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.

Example

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

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

Contains the reason why the ETA was not provided.

Description

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

Type declaration

Name	Type	Description
`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.
`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.

Description

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,
   "second": 0
 },
 "latestAttemptTime": {
   "hour": 10,
   "minute": 0,
   "second": 0
 },
 "estimatedAttemptDuration": 300
}

Type declaration

Name	Type	Description
`earliestAttemptTime`	`TimeOfDay` \| `null`	Earliest attemp time this stop should occur at. `Default` `ts null`
`latestAttemptTime`	`TimeOfDay` \| `null`	Latest attemp time this stop should occur at. `Default` `ts 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` `ts null`

TimeOfDay

Ƭ TimeOfDay: Object

The time of day in hours and minutes.

Description

The time of day in hours and minutes.

Example

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

Type declaration

Name	Type
`hour`	`number`
`minute`	`number`

DeliveryState

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_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_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

A location object with latitude and longitude.

Example

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

Type declaration

Name	Type
`latitude`	`number`
`longitude`	`number`

Model​

Stop​

Type declaration​

Identifier​

StopId​

Fields​

StopAddress​

Type declaration​

StopRecipient​

Type declaration​

DeliveryInfo​

Type declaration​

OrderInfo​

Type declaration​

PlaceInVehicle​

Type declaration​

ETAData​

Type declaration​

ETADataNullReason​

Type declaration​

TimingData​

Type declaration​

TimeOfDay​

Type declaration​

DeliveryState​

StopActivity​

Location​

Type declaration​

Model

Stop

Type declaration

Identifier

StopId

Fields

StopAddress

Type declaration

StopRecipient

Type declaration

DeliveryInfo

Type declaration

OrderInfo

Type declaration

PlaceInVehicle

Type declaration

ETAData

Type declaration

ETADataNullReason

Type declaration

TimingData

Type declaration

TimeOfDay

Type declaration

DeliveryState

StopActivity

Location

Type declaration