---
title: "Retrieve a stop"
method: GET
path: "/plans/{planId}/stops/{stopId}"
tags: ["Stops"]
---

# Retrieve a stop

`GET /plans/{planId}/stops/{stopId}`

## Request

- Base URL: `https://api.spoke.com/public/v1`
- URL: `https://api.spoke.com/public/v1/plans/{planId}/stops/{stopId}`
- Auth: HTTP basic
- TypeScript: <https://skmtc.dev/spoke/apis/spoke-api/docs/plans/:planId/stops/:stopId/get.ts> (a function with typed inputs; its response is checked against the schema)

Retrieve a stop

## Path parameters

- `planId` string, required
- `stopId` string, required

## Response `200`

The requested stop

- StopSchema: A stop of a plan, can be related to a route.
  - `id` string, required
  - `address` object, required: The address of the stop.
    - `address` string, required: The address of the stop.
    - `addressLineOne` string, required: The first line of the address.
    - `addressLineTwo` string, required: The second line of the address.
    - `latitude` number, nullable, required: The latitude of the address in decimal degrees.
    - `longitude` number, nullable, required: The longitude of the address in decimal degrees.
    - `placeId` string, nullable, required: The identifier of the place corresponding to this stop on Google Places
    - `placeTypes` string[], required: Array of strings that is provided by the Google AutoCompleteAPI
  - `barcodes` string[], required: List of Barcode IDs associated with the stop.
  - `allowedDrivers` string[], required: The driver IDs that can be assigned to this stop
  - `estimatedTravelDuration` number, nullable, required: Estimated time that the driver will take to arrive at this stop from the previous stop in seconds.
  - `estimatedTravelDistance` number, nullable, required: The distance in meters between the previous stop and this stop.
  - `notes` string, nullable, required: Notes for the stop.
  - `packageCount` number, nullable, required: The number of packages.
  - `weight` object, nullable, required: Weight information for the stop.
    - `amount` number, required: The weight amount for this stop.
    - `unit` 'kilogram' | 'pound' | 'metric-ton', required: The weight unit in which the amount is specified (defined at team's capacity unit).
  - `type` 'start' | 'stop' | 'end', required: The type of the stop. `start` is the first stop of the route, `stop` is a stop in the middle of the route, and `end` is the last stop of the route.
  - `packageLabel` string, nullable, required: The label of the package.
  - `stopPosition` number, nullable, required: The position of the stop in the route.
  - `trackingLink` string, nullable, required: The recipient tracking link.
  - `webAppLink` string, required: The web app link.
  - `orderInfo` object, required: The order information of the stop.
    - `products` string[], required: The products of the stop.
    - `invoiceNumber` string, nullable, required: Invoice number associated with the order.
    - `sellerName` string, nullable, required: Name of the seller where the order is from.
    - `sellerOrderId` string, nullable, required: Id of the seller where the order is from.
    - `sellerWebsite` string, nullable, required: Website of the seller where the order is from.
  - `placeInVehicle` object, nullable, required: The position of the package in the vehicle.
    - `x` 'left' | 'right', nullable, required: The x position of the package.
    - `y` 'front' | 'back' | 'middle', nullable, required: The y position of the package.
    - `z` 'floor' | 'shelf', nullable, required: The z position of the package.
  - `recipient` object, required: The recipient of the stop.
    - `name` string, nullable, required: The name of the recipient.
    - `email` string, nullable, required: The email of the recipient.
    - `phone` string, nullable, required: The phone of the recipient.
    - `externalId` string, nullable, required: The external id of the recipient.
  - `activity` 'delivery' | 'pickup'
  - `deliveryInfo` object, nullable, required: The delivery information of the stop.
    - `attempted` boolean, required: Whether the stop was attempted.
    - `attemptedAt` number, nullable, required: When the stop was attempted in seconds since epoch.
    - `timeAtStopInfo` union, required
      - object
        - `status` 'available', required
        - `value` object, required: Grouped time-at-stop data.
          - `arrivedAt` number, nullable, required: When the driver arrived at the stop in seconds since epoch.
          - `departedAt` number, nullable, required: When the driver departed from the stop in seconds since epoch.
          - `isEstimated` boolean, nullable, required: Whether the time at stop was estimated rather than directly measured.
      - object
        - `status` 'restricted', required
        - `requiredFeature` string
        - `upgradeUrl` string
        - `restrictionCode` 'subscription_not_supported'
      - object
        - `status` 'pending', required
        - `pendingReason` 'not_yet_arrived'
    - `attemptedLocation` object, nullable, required: A location.
      - `latitude` number, required: The latitude of the location.
      - `longitude` number, required: The longitude of the location.
    - `driverProvidedInternalNotes` string, nullable, required: Internal notes provided by the driver.
    - `driverProvidedRecipientNotes` string, nullable, required: Recipient notes provided by the driver.
    - `photoUrls` string[], required: URLs of proof of delivery photos.
    - `recipientProvidedNotes` string, nullable, required: Notes from recipient
    - `signatureUrl` string, nullable, required: URL of the signature.
    - `signeeName` string, nullable, required: Name of the signee.
    - `succeeded` boolean, required: Whether the stop was succeeded.
    - `state` '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_other' | 'failed_missing_required_proof' | 'failed_payment_not_received' | 'unattempted', required: The state of the delivery.
  - `paymentOnDelivery` object, nullable, required: The payment due upon delivery also known as "Cash on Delivery".
    - `amount` integer, nullable, required: The amount *in minor units* (e.g. cents) to be collected upon delivery.
    - `currency` string, required: The payment's currency in ISO 4217 standard.
  - `proofOfAttemptRequirements` object, required: The proof of attempt requirements of the stop.
    - `enabled` boolean, nullable, required: Whether the proof of attempt is enabled.This only works if the team subscription has access to proof of delivery
  - `plan` string, required
  - `route` RouteSchema, required: A route.
    - `id` string, required
    - `title` string, required: The title of the route.
    - `stopCount` number, required: The number of stops in the route.
    - `driver` string, required
    - `state` object, nullable, required: The state of a route.
      - `completed` boolean, required: Whether the route is completed.
      - `completedAt` number, nullable, required: The timestamp the route was completed at.
      - `distributed` boolean, required: Whether the route is distributed.
      - `distributedAt` number, nullable, required: The timestamp the route was distributed at.
      - `notifiedRecipients` boolean, required: Whether the recipients were notified.
      - `notifiedRecipientsAt` number, nullable, required: The timestamp the recipients were notified at.
      - `started` boolean, required: Whether the route is started.
      - `startedAt` number, nullable, required: The timestamp the route was started at.
    - `plan` string, required
  - `eta` union, required
    - object
      - `status` 'available', required
      - `value` object, required: The estimated time of arrival data of the stop.
        - `estimatedArrivalAt` number, required: The estimated time in seconds since epoch.
        - `estimatedLatestArrivalAt` number, required: The latest estimated time in seconds since epoch.
        - `estimatedEarliestArrivalAt` number, required: The earliest estimated time in seconds since epoch.
    - object
      - `status` 'restricted', required
      - `requiredFeature` string
      - `upgradeUrl` string
      - `restrictionCode` 'subscription_not_supported'
    - object
      - `status` 'pending', required
      - `pendingReason` 'not_optimized'
  - `timing` object, required: The timing data of the stop.
    - `timeWindows` object[], required: Ordered arrival windows for this stop.
      - `earliestAttemptTime` TimeOfDaySchema, required: Time of day in hours and minutes. Uses a 24 hour clock.
        - `hour` integer, required: Hour of the day
        - `minute` integer, required: Minute of the hour
      - `latestAttemptTime` TimeOfDaySchema, required: Time of day in hours and minutes. Uses a 24 hour clock.
        - `hour` integer, required: Hour of the day
        - `minute` integer, required: Minute of the hour
    - `estimatedAttemptDuration` number, nullable, required: Time that the driver estimates to spend on the stop to do his job (deliver a parcel, visit a client, etc) in seconds.
    - `earliestAttemptTime` TimeOfDaySchema, required: Time of day in hours and minutes. Uses a 24 hour clock.
      - `hour` integer, required: Hour of the day
      - `minute` integer, required: Minute of the hour
    - `latestAttemptTime` TimeOfDaySchema, required: Time of day in hours and minutes. Uses a 24 hour clock.
      - `hour` integer, required: Hour of the day
      - `minute` integer, required: Minute of the hour
  - `optimizationOrder` 'first' | 'last' | 'default'
  - `customProperties` object, nullable, required: Custom properties of the stop, can be used to store additional information.
  - `clientId` string, nullable, required: The associated Client ID of the Spoke Connect
  - `serviceInfo` union, required: Service offering data for this stop.
    - object
      - `status` 'available', required
      - `value` union, required: Service offering data for this stop.
        - object: Service offering data when a service is assigned to the stop.
          - `identifier` string, required: The service offering identifier, as configured in Spoke Dispatch, captured at assignment time. Not currently discoverable through the public API.
          - `name` string, required: The human-readable service name.
          - `slaStartsAt` number, required: The SLA start time in seconds since epoch.
          - `slaDueDate` object, required: The computed SLA due date in the team's timezone.
            - `day` integer, required: The day of the date.
            - `month` integer, required: The month of the date.
            - `year` integer, required: The year of the date.
          - `slaDueTime` TimeOfDaySchema, required: Time of day in hours and minutes. Uses a 24 hour clock.
            - `hour` integer, required: Hour of the day
            - `minute` integer, required: Minute of the hour
          - `deliveryHorizon` object, required: The delivery horizon for this service.
            - `unit` union, required: The time unit of the delivery horizon. Known: `days`, `hours`.
              - …
            - `value` number, required: The number of time units in the delivery horizon.
          - `price` object, required: Price for this service at assignment time.
            - `value` number, required: Price in minor currency units (e.g. cents).
            - `currency` union, required: 3-letter ISO 4217 currency code.
              - …
          - `hasPaymentOnDelivery` boolean, required: Whether cash on delivery is enabled via the service.
          - `definedAt` number, required: When the service was assigned in seconds since epoch.
        - object: Service data when only an SLA start time is set.
          - `identifier` unknown, required
          - `slaStartsAt` number, required: The SLA start time in seconds since epoch.
    - object
      - `status` 'empty', required
    - object
      - `status` 'restricted', required
      - `requiredFeature` string
      - `upgradeUrl` string
      - `restrictionCode` 'subscription_not_supported'

## Other responses

- `400`: ID format is invalid
- `401`: Unauthorized
- `403`: Plan is no longer accessible due to data access restrictions. Upgrade to a plan that supports a longer delivery history period to access it.
- `404`: Not Found
- `500`: An internal server error occurred
- `default`: The default error model

---

[API](https://skmtc.dev/spoke/apis/spoke-api.md) - [All operations](https://skmtc.dev/spoke/apis/spoke-api/llms.txt) - [OpenAPI document](https://skmtc.dev/spoke/apis/spoke-api/revisions/a09d9194ae1c?raw)