Circuit Live Stops API

openapi: 3.2.0
info:
  title: Spoke Live Stops API
  description: This is the documentation of the Spoke Public API HTTP endpoints.
  version: v1
servers:
- url: https://api.spoke.com/public/v1
security:
- BasicAuth: []
tags:
- name: Live Stops
  description: 'Endpoints to operate on Stop resources when the plan is already optimized and therefore not writable.


    All the endpoints return the field `pending`. This field indicates whether the

    change has been applied to the plan or if it''s pending a new optimization and distribution. On `pending = true`,

    you must use the re-optimize and re-distribute

    endpoints to apply the changes to the plan.'
paths:
  /plans/{planId}/stops:liveCreate:
    post:
      operationId: createLiveStop
      summary: Create a new stop
      tags:
      - Live Stops
      description: Create a new stop with the given data on live plans. When the plan is not writable, this endpoint starts an editing session and the action can be applied through a new optimization, or be discarded. Prefer using the batch import endpoint if you want to create multiple stops at once as it is more efficient and will produce better geocoding results.
      requestBody:
        content:
          application/json:
            schema:
              description: The request body for creating a stop. The only required field is address, you need to provide at least one of the fields in it. The latitude and longitude fields will override any of the other fields if they are set(and they need to be both set if any of them are). The more fields you provide the more accurate the geocoding will be.
              type: object
              properties:
                address:
                  type: object
                  properties:
                    addressName:
                      description: The name of the address. This will not be used for geocoding, and is only for the final address display purposes.
                      anyOf:
                      - type: string
                        minLength: 1
                        maxLength: 255
                      - type: 'null'
                    addressLineOne:
                      description: The first line of the address.
                      anyOf:
                      - type: string
                        minLength: 1
                        maxLength: 255
                      - type: 'null'
                    addressLineTwo:
                      description: The second line of the address.
                      anyOf:
                      - type: string
                        minLength: 1
                        maxLength: 255
                      - type: 'null'
                    city:
                      description: The city of the address.
                      anyOf:
                      - type: string
                        minLength: 1
                        maxLength: 100
                      - type: 'null'
                    state:
                      description: The state of the address.
                      anyOf:
                      - type: string
                        minLength: 1
                        maxLength: 100
                      - type: 'null'
                    zip:
                      description: The zip code of the address.
                      anyOf:
                      - type: string
                        minLength: 1
                        maxLength: 100
                      - type: 'null'
                    country:
                      description: The country of the address.
                      anyOf:
                      - type: string
                        minLength: 1
                        maxLength: 100
                      - type: 'null'
                    latitude:
                      description: The latitude of the address in decimal degrees.
                      anyOf:
                      - type: number
                        minimum: -90
                        maximum: 90
                      - type: 'null'
                    longitude:
                      description: The longitude of the address in decimal degrees.
                      anyOf:
                      - type: number
                        minimum: -180
                        maximum: 180
                      - type: 'null'
                  additionalProperties: false
                timing:
                  anyOf:
                  - description: Timing information for this stop
                    type: object
                    properties:
                      earliestAttemptTime:
                        description: Time of day of the earliest time this stop should happen
                        anyOf:
                        - description: Time of day in hours and minutes. Use a 24 hour clock.
                          type: object
                          properties:
                            hour:
                              description: Hour of the day
                              type: integer
                              minimum: -9007199254740991
                              maximum: 9007199254740991
                            minute:
                              description: Minute of the hour
                              type: integer
                              minimum: -9007199254740991
                              maximum: 9007199254740991
                          required:
                          - hour
                          - minute
                          additionalProperties: false
                        - type: 'null'
                      latestAttemptTime:
                        description: Time of day of the latest time this stop should happen
                        anyOf:
                        - description: Time of day in hours and minutes. Use a 24 hour clock.
                          type: object
                          properties:
                            hour:
                              description: Hour of the day
                              type: integer
                              minimum: -9007199254740991
                              maximum: 9007199254740991
                            minute:
                              description: Minute of the hour
                              type: integer
                              minimum: -9007199254740991
                              maximum: 9007199254740991
                          required:
                          - hour
                          - minute
                          additionalProperties: false
                        - type: 'null'
                      estimatedAttemptDuration:
                        description: Duration in seconds of the activity in this stop, only set if you want to override the default. This can be set up to 8 hours.
                        anyOf:
                        - type: integer
                          minimum: -9007199254740991
                          maximum: 9007199254740991
                        - type: 'null'
                    additionalProperties: false
                  - type: 'null'
                recipient:
                  anyOf:
                  - description: Recipient information for this stop
                    type: object
                    properties:
                      externalId:
                        description: External ID of the recipient, as defined by the API user
                        anyOf:
                        - type: string
                          minLength: 1
                          maxLength: 255
                        - type: 'null'
                      email:
                        description: Email of the recipient
                        anyOf:
                        - type: string
                          minLength: 1
                          maxLength: 255
                        - type: 'null'
                      phone:
                        description: Phone number of the recipient
                        anyOf:
                        - type: string
                          minLength: 1
                          maxLength: 255
                        - type: 'null'
                      name:
                        description: Name of the recipient
                        anyOf:
                        - type: string
                          minLength: 1
                          maxLength: 255
                        - type: 'null'
                    additionalProperties: false
                  - type: 'null'
                orderInfo:
                  anyOf:
                  - description: Order information for this stop
                    type: object
                    properties:
                      products:
                        description: Products in this stop
                        maxItems: 100
                        type: array
                        items:
                          type: string
                          minLength: 1
                          maxLength: 255
                      invoiceNumber:
                        description: Invoice number
                        anyOf:
                        - type: string
                          minLength: 1
                          maxLength: 255
                        - type: 'null'
                      sellerOrderId:
                        description: Seller order ID
                        anyOf:
                        - type: string
                          minLength: 1
                          maxLength: 255
                        - type: 'null'
                      sellerName:
                        description: Seller name
                        anyOf:
                        - type: string
                          minLength: 1
                          maxLength: 255
                        - type: 'null'
                      sellerWebsite:
                        description: Seller website
                        anyOf:
                        - type: string
                          minLength: 1
                          maxLength: 255
                        - type: 'null'
                    additionalProperties: false
                  - type: 'null'
                paymentOnDelivery:
                  anyOf:
                  - description: Payment on delivery (also known as "Cash on Delivery") data for this stop
                    type: object
                    properties:
                      amount:
                        description: Amount *in minor units* (e.g. cents) to be collected upon delivery
                        anyOf:
                        - type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        - type: 'null'
                      currency:
                        description: Currency of the payment. Defaults to the team's currency.
                        anyOf:
                        - type: string
                          enum:
                          - AED
                          - ARS
                          - AUD
                          - BRL
                          - CAD
                          - CHF
                          - CLP
                          - CNY
                          - COP
                          - DKK
                          - EGP
                          - EUR
                          - GBP
                          - HKD
                          - HUF
                          - ILS
                          - INR
                          - JPY
                          - KRW
                          - MYR
                          - MXN
                          - NOK
                          - NZD
                          - PEN
                          - RON
                          - RUB
                          - SAR
                          - SEK
                          - SGD
                          - TRY
                          - USD
                          - UYU
                          - ZAR
                        - type: 'null'
                    additionalProperties: false
                  - type: 'null'
                proofOfAttemptRequirements:
                  anyOf:
                  - description: Proof of attempt requirement settings for this stop
                    type: object
                    properties:
                      enabled:
                        description: Whether proof of attempt is required for this stop
                        anyOf:
                        - type: boolean
                        - type: 'null'
                    additionalProperties: false
                  - type: 'null'
                allowedDrivers:
                  description: Driver IDs that are allowed to be assigned to this stop. These drivers must be configured as part of the plan to be valid.
                  anyOf:
                  - maxItems: 100
                    type: array
                    items:
                      type: string
                      pattern: ^drivers\/[a-zA-Z0-9---_]{1,50}$
                  - type: 'null'
                activity:
                  description: Activity type
                  default: delivery
                  anyOf:
                  - type: string
                    enum:
                    - delivery
                    - pickup
                  - type: 'null'
                optimizationOrder:
                  description: The preferred order of this stop in the optimized route. If not provided or `"default"`, the stop will be placed in the optimal order, decided by the optimization algorithm. Otherwise it will be placed either `"first"` or `"last"`.
                  anyOf:
                  - type: string
                    enum:
                    - first
                    - last
                    - default
                  - type: 'null'
                packageCount:
                  description: Number of packages in the stop
                  anyOf:
                  - type: number
                    minimum: 1
                    maximum: 10000
                  - type: 'null'
                weight:
                  description: Weight information for this stop.
                  anyOf:
                  - type: object
                    properties:
                      amount:
                        description: The weight amount for this stop.
                        type: number
                        minimum: 0
                        maximum: 999999
                        multipleOf: 0.01
                      unit:
                        description: The weight unit in which the amount is specified.
                        type: string
                        enum:
                        - kilogram
                        - pound
                        - metric-ton
                    required:
                    - amount
                    - unit
                  - type: 'null'
                notes:
                  description: Notes for the stop
                  anyOf:
                  - type: string
                    minLength: 1
                    maxLength: 2000
                  - type: 'null'
                clientId:
                  description: Client ID of the retailer in Spoke Connect
                  anyOf:
                  - type: string
                    minLength: 1
                    maxLength: 100
                  - type: 'null'
                barcodes:
                  description: List of barcode IDs associated with this stop
                  maxItems: 200
                  type: array
                  items:
                    type: string
                    minLength: 1
                    maxLength: 255
                customProperties:
                  description: Key-value pairs of custom stop properties for this stop. The keys must be unique and match a custom stop property defined in your team.
                  anyOf:
                  - type: object
                    propertyNames:
                      description: The custom stop property id
                      type: string
                      maxLength: 50
                    additionalProperties:
                      description: The value of the custom stop property, up to 255 characters.
                      anyOf:
                      - type: string
                        minLength: 1
                        maxLength: 255
                      - type: 'null'
                  - type: 'null'
                serviceInfo:
                  anyOf:
                  - description: Service offering data for this stop. Combines the service identifier and SLA start time. On update, set the whole object to `null` to clear all service info.
                    type: object
                    properties:
                      identifier:
                        anyOf:
                        - description: The identifier of a service offering to assign to this stop. Must match the identifier of a current, non-deleted service offering defined on your team. On update, set it to `null` to remove an assigned service; on create, omit it to leave the stop without a service.
                          type: string
                          minLength: 1
                          maxLength: 32
                          pattern: ^[a-zA-Z0-9]+$
                        - type: 'null'
                      slaStartsAt:
                        anyOf:
                        - description: The SLA start time for this stop, in seconds since Unix epoch. Allows backdating when the actual order time is known. Can be provided with or without a service identifier.
                          type: integer
                          exclusiveMinimum: 0
                          maximum: 9007199254740991
                        - type: 'null'
                    additionalProperties: false
                  - type: 'null'
              required:
              - address
              additionalProperties: false
        required: true
        description: The request body for creating a stop. The only required field is address, you need to provide at least one of the fields in it. The latitude and longitude fields will override any of the other fields if they are set(and they need to be both set if any of them are). The more fields you provide the more accurate the geocoding will be.
      parameters:
      - schema:
          type: string
          pattern: ^[a-zA-Z0-9---_]{1,50}$
        in: path
        name: planId
        required: true
        description: The plan id
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  pending:
                    type: boolean
                  stop:
                    $ref: '#/components/schemas/stopSchema'
                required:
                - pending
                - stop
                definitions:
                  stopSchema:
                    type: object
                    properties:
                      id:
                        type: string
                        pattern: ^plans\/[a-zA-Z0-9---_]{1,50}\/stops\/[a-zA-Z0-9---_]{1,50}$
                        description: The id of the stop, in the format `plans/<id>/stops/<id>`.
                      address:
                        type: object
                        properties:
                          address:
                            type: string
                            description: The address of the stop.
                          addressLineOne:
                            type: string
                            description: The first line of the address.
                          addressLineTwo:
                            type: string
                            description: The second line of the address.
                          latitude:
                            anyOf:
                            - type: number
                              minimum: -90
                              maximum: 90
                            - type: 'null'
                            description: The latitude of the address in decimal degrees.
                          longitude:
                            anyOf:
                            - type: number
                              minimum: -180
                              maximum: 180
                            - type: 'null'
                            description: The longitude of the address in decimal degrees.
                          placeId:
                            anyOf:
                            - type: string
                            - type: 'null'
                            description: The identifier of the place corresponding to this stop on Google Places
                          placeTypes:
                            type: array
                            items:
                              type: string
                            description: Array of strings that is provided by the Google AutoCompleteAPI
                        required:
                        - address
                        - addressLineOne
                        - addressLineTwo
                        - latitude
                        - longitude
                        - placeId
                        - placeTypes
                        additionalProperties: false
                        description: The address of the stop.
                      barcodes:
                        type: array
                        items:
                          type: string
                        description: List of Barcode IDs associated with the stop.
                      allowedDrivers:
                        type: array
                        items:
                          type: string
                          pattern: ^drivers\/[a-zA-Z0-9---_]{1,50}$
                        description: The driver IDs that can be assigned to this stop
                      estimatedTravelDuration:
                        anyOf:
                        - type: number
                        - type: 'null'
                        description: Estimated time that the driver will take to arrive at this stop from the previous stop in seconds.
                      estimatedTravelDistance:
                        anyOf:
                        - type: number
                        - type: 'null'
                        description: The distance in meters between the previous stop and this stop.
                      notes:
                        anyOf:
                        - type: string
                        - type: 'null'
                        description: Notes for the stop.
                      packageCount:
                        anyOf:
                        - type: number
                        - type: 'null'
                        description: The number of packages.
                      weight:
                        anyOf:
                        - type: object
                          properties:
                            amount:
                              type: number
                              minimum: 0
                              description: The weight amount for this stop.
                            unit:
                              type: string
                              enum:
                              - kilogram
                              - pound
                              - metric-ton
                              description: The weight unit in which the amount is specified (defined at team's capacity unit).
                          required:
                          - amount
                          - unit
                          additionalProperties: false
                          description: Weight information for the stop.
                        - type: 'null'
                      type:
                        type: string
                        enum:
                        - start
                        - stop
                        - end
                        description: 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:
                        anyOf:
                        - type: string
                        - type: 'null'
                        description: The label of the package.
                      stopPosition:
                        anyOf:
                        - type: number
                        - type: 'null'
                        description: The position of the stop in the route.
                      trackingLink:
                        anyOf:
                        - type: string
                        - type: 'null'
                        description: The recipient tracking link.
                      webAppLink:
                        type: string
                        description: The web app link.
                      orderInfo:
                        type: object
                        properties:
                          products:
                            type: array
                            items:
                              type: string
                            description: The products of the stop.
                          invoiceNumber:
                            anyOf:
                            - type: string
                            - type: 'null'
                            description: Invoice number associated with the order.
                          sellerName:
                            anyOf:
                            - type: string
                            - type: 'null'
                            description: Name of the seller where the order is from.
                          sellerOrderId:
                            anyOf:
                            - type: string
                            - type: 'null'
                            description: Id of the seller where the order is from.
                          sellerWebsite:
                            anyOf:
                            - type: string
                            - type: 'null'
                            description: Website of the seller where the order is from.
                        required:
                        - products
                        - invoiceNumber
                        - sellerName
                        - sellerOrderId
                        - sellerWebsite
                        additionalProperties: false
                        description: The order information of the stop.
                      placeInVehicle:
                        anyOf:
                        - type: object
                          properties:
                            x:
                              anyOf:
                              - type: string
                                enum:
                                - left
                                - right
                              - type: 'null'
                              description: The x position of the package.
                            y:
                              anyOf:
                              - type: string
                                enum:
                                - front
                                - back
                                - middle
                              - type: 'null'
                              description: The y position of the package.
                            z:
                              anyOf:
                              - type: string
                                enum:
                                - floor
                                - shelf
                              - type: 'null'
                              description: The z position of the package.
                          required:
                          - x
                          - y
                          - z
                          additionalProperties: false
                          description: The position of the package in the vehicle.
                        - type: 'null'
                      recipient:
                        type: object
                        properties:
                          name:
                            anyOf:
                            - type: string
                            - type: 'null'
                            description: The name of the recipient.
                          email:
                            anyOf:
                            - type: string
                            - type: 'null'
                            description: The email of the recipient.
                          phone:
                            anyOf:
                            - type: string
                            - type: 'null'
                            description: The phone of the recipient.
                          externalId:
                            anyOf:
                            - type: string
                            - type: 'null'
                            description: The external id of the recipient.
                        required:
                        - name
                        - email
                        - phone
                        - externalId
                        additionalProperties: false
                        description: The recipient of the stop.
                      activity:
                        default: delivery
                        type: string
                        enum:
                        - delivery
                        - pickup
                      deliveryInfo:
                        anyOf:
                        - type: object
                          properties:
                            attempted:
                              type: boolean
                              description: Whether the stop was attempted.
                            attemptedAt:
                              anyOf:
                              - type: number
                              - type: 'null'
                              description: When the stop was attempted in seconds since epoch.
                            timeAtStopInfo:
                              oneOf:
                              - type: object
                                properties:
                                  status:
                                    type: string
                                    enum:
                                    - available
                                  value:
                                    type: object
                                    properties:
                                      arrivedAt:
                                        anyOf:
                                        - type: number
                                        - type: 'null'
                                        description: When the driver arrived at the stop in seconds since epoch.
                                      departedAt:
                                        anyOf:
                                        - type: number
                                        - type: 'null'
                                        description: When the driver departed from the stop in seconds since epoch.
                                      isEstimated:
                                        anyOf:
                                        - type: boolean
                                        - type: 'null'
                                        description: Whether the time at stop was estimated rather than directly measured.
                                    required:
                                    - arrivedAt
                                    - departedAt
                                    - isEstimated
                                    additionalProperties: false
                                    description: Grouped time-at-stop data.
                                required:
                                - status
                                - value
                                additionalProperties: false
                              - type: object
                                properties:
                                  status:
                                    type: string
                                    enum:
                                    - restricted
              

# --- truncated at 32 KB (203 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/circuit/refs/heads/main/openapi/circuit-live-stops-api-openapi.yml