openapi: 3.1.0 info: title: Spoke Depots Stops API description: "This is the documentation of the Spoke Public API HTTP endpoints. The Spoke\nPublic API is a way for you to interact with Spoke products programmatically.\n\n# Introduction\n\nThe API has a set of HTTP methods to operate on Spoke resources for a specific\nteam.\n\nCurrently, Spoke offers no programming SDKs for interacting with the Public\nAPI, but you can implement your own interface by calling the methods documented\non this page.\n\n# Using the API\n\nThis section describes how the Spoke API should be used, if you wish to see\nexample implementations take a look at the [API Usage\nExamples](/docs/api-examples) page.\n\n## Address\n\nThe base API address for this version of the API to be used before every\nendpoint listed here is: `https://api.spoke.com/public/v0.2b`\n\nNotice the `https://` prefix, Spoke API will **not** accept plain HTTP\nrequests.\n\n## Authentication\n\nTo use Spoke Public API endpoints you will first need to generate an API key\nfor authenticating with our servers.\n\nTo do this you need to go to your Spoke Dispatch settings page > Integrations\n\\> API, and generate a new key there.\n\nOnce you have the API key you can use it in the `Authorization` header\neither using the Basic scheme, or as a Bearer token.\n\n### Basic Auth\n\n[Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) is the primary authentication scheme used\nby Spoke's API.\n\nBasic authentication typically uses a base64 encoded `username:password`\npair, but since we only require an API key we instead structure the payload as `[yourApiKey]:[empty]`. This\nvalue is then base64 encoded as usual.\n\nExample with `curl`:\n\n```bash\ncurl \"https://api.spoke.com/public/v0.2b/plans\" -u yourApiKey:\n```\n\nIf you did everything correctly you should see a list of your team's plans in response\nto this request.\n\nThe `-u` flag adds a header to the request in the following format:\n\n```http\nAuthorization: Basic eW91ckFwaUtleToK\n```\n\nNote that curl automatically base64 encoded the data. Other clients will do the same e.g. if using Postman you would\nconfigure the request's Authorization option instead of adding a header directly.\n\n### Bearer Token\n\nAlternatively you can pass the API key as a Bearer token without any special encoding.\ni.e. `Authorization: Bearer [yourApiKey]`.\n\nExample with `curl`:\n\n```bash\ncurl \"https://api.spoke.com/public/v0.2b/plans\" -H \"Authorization: Bearer yourApiKey\"\n```\n\n## On resource types\n\nEvery response from the Spoke Public API will be as JSON Objects, and every\nrequest that has a body also needs to be in that type, and the header\n`Content-type: application/json` needs to present, so the server knows that the\nbody you are sending is valid JSON. Spoke will reject requests without that\nheader, so be sure to use it.\n\n## On resource IDs\n\nEvery resource in the Spoke Public API has a unique ID. This ID is generated\nby Spoke and is unique for every resource per collection.\n\nEvery resource representation returned by the API will show the ID in the\nfollowing format:\n\n```json\n{\n \"id\": \"collectionName/resourceId\"\n}\n```\n\nAnd if the resource is on a sub-collection, it will be in the following format:\n\n```json\n{\n \"id\": \"collectionName/resourceId/subcollectionName/subResourceId\"\n}\n```\n\nFor example, a stop with ID `stop1` under a plan with ID `plan1` will have the\nfollowing representation on its serialized ID field:\n\n```json\n{\n \"id\": \"plans/plan1/stops/stop1\"\n}\n```\n\nThis means that if you wish to directly retrieve this stop by using a GET\nendpoint you can simply use this ID as follows:\n\n```bash\ncurl \"https://api.spoke.com/public/v0.2b/`serializedId`\" -u yourApiKey:\n```\n\nFor the example above this would be:\n\n```bash\ncurl \"https://api.spoke.com/public/v0.2b/plans/plan1/stops/stop1\" -u yourApiKey:\n```\n\n## On List endpoints\n\nWhen using list endpoints, you have the ability to combine various query options\nto locate the desired results. Some endpoints even offer specific filter options\nto aid in this search.\n\nAll the list endpoints employ pagination. This means that a single request might\nonly return a part of the entire set of resources you're aiming to retrieve. To\nmove through the subsequent pages, the Spoke API provides a `nextPageToken`\nfield in the response of every list endpoint query.\n\nIt's crucial to understand that when a `nextPageToken` is returned, it indicates\nthat more data is available. For every subsequent request, this token should be\nadded as the `pageToken` query parameter. And, importantly, **all the original\nquery parameters** used in the first request must also be included.\n\nHere's a step-by-step example to elucidate this:\n\n1. Suppose you initiate a request to list your plans:\n\n```bash\ncurl \"https://api.spoke.com/public/v0.2b/plans?filter.startsGte=2023-05-01\" -u yourApiKey:\n```\n\n2. The Spoke API might return a response like:\n\n```json\n{\n // other attributes\n \"nextPageToken\": \"I53Jr5Eu2qK9omh0iA8q\"\n}\n```\n\n3. To retrieve the next page of data, use the returned `nextPageToken` as the\n `pageToken` query parameter, and ensure all initial query parameters remain\n the same:\n\n```bash\ncurl \"https://api.spoke.com/public/v0.2b/plans?filter.startsGte=2023-05-01&pageToken=I53Jr5Eu2qK9omh0iA8q\" -u yourApiKey:\n```\n\n4. Repeat step 3 for all subsequent pages, updating the `pageToken` parameter\n with the latest `nextPageToken` value returned until `nextPageToken` is\n `null` in the response.\n\nSpoke also accepts limiting the maximum number of results per page by using\nthe `maxPageSize` query parameter, but notice that each individual endpoint has\na maximum value you can set this to.\n\n## On Update endpoints (HTTP PATCH verb)\n\nUpdate methods differ from the other methods in the API in the sense that\nmissing values in the JSON representation will **not** act upon the\nrepresentation of the resource.\n\nExplaining this by example: Suppose you have a Plan with the ID `plan1` in your\nplans' collection, and you wanted to merely update its title to `My API Plan`\nwithout changing other information, such as assigned drivers or the start date.\nTo do this you would issue the following request:\n\n```bash\ncurl -X PATCH http://localhost:5005/public/v0.2b/plans/plan1 -H 'Content-type: application/json' -d '{\"title\": \"My API Plan\"}' -u yourApiKey:\n```\n\nNotice how we don't pass any other information in the JSON, only the title. This\nensures that the `PATCH` request will only operate on the provided parameters\nand keep the other parameters as-is.\n\nIt is important to also notice that when updating an array the whole array will\nbe replaced, Spoke API does not support partial updates on arrays.\n\n## On Rate-Limiting\n\nAll the endpoints in the Spoke Public API are rate-limited, which means we\nwill reject requests that come in too fast.\n\nTo know if your request was rate-limited, check if the response has the HTTP\nstatus code 429.\n\nEach endpoint has a different rate limit, and Spoke can change this rate\nlimit at any moment.\n\nThe rate limits are as follows:\n\n- **Rate Limits for Write Endpoints**: All write endpoints have a limit of 5\n requests per second, which includes Creation (POST), Update (PATCH), and\n Deletion (DELETE) operations for all models.\n - An exception to this rule is the Driver Creation endpoint, which is limited to\n 1 request per second. Thus, we recommend using the Batch Import Drivers\n when adding multiple drivers.\n- **Rate Limits for Read Endpoints**: All read endpoints, including list\n endpoints, are limited to 10 requests per second.\n- **Rate Limits for Batch Import**:\n - The _Batch Import_ endpoints for Stops and Unassigned Stops models are\n limited to 100 requests per _10 minutes_ (with a maximum rate of 30 per _minute_).\n However, these endpoints can handle the import of up to 1,000 stops per minute.\n The Creation, Update, and Deletion endpoints for these models still maintain\n a rate limit of 5 requests per second.\n - The _Batch Import_ endpoint for Drivers is limited to 2 requests per\n _minute_. This allows for the import of up to 100 drivers per minute.\n- **Rate Limits for Optimization Endpoints**: The Plan _optimization_ and\n _re-optimization_ endpoints are limited to 100 requests per _10 minutes_\n (with a maximum rate of 30 per _minute_), due to the long running nature of these operations.\n\nSpoke API will occasionally support bursts of requests, but they cannot be\nsustained and will be rejected if they last too long.\n\nIf Spoke rejects your request because it exceeds the rate limit, you must\nwait before retrying it. We suggest you use an [exponential\nbackoff](https://en.wikipedia.org/wiki/Exponential_backoff) approach for this.\n\nWe also recommend, besides the exponential backoff algorithm, that you add a\nrandom delay to each attempt to prevent a [thundering herd\nproblem](https://en.wikipedia.org/wiki/Thundering_herd_problem).\n\nIf the client keeps retrying rate-limited requests while being rejected with a\n429 at a high rate, Spoke will keep rejecting the requests until you turn\ndown the request rate.\n\nSpoke will also limit requests if it keeps receiving them at a high frequency\nat or close to the requests limit for an extended period, so while we support\nan occasional burst of requests, if this is sustained for a long period, we\nwill rate-limit the client making them.\n\nWhile we feel these rate-limits will work for the vast majority of use cases we\nunderstand every team is different. So please reach out to us and describe your\nuse case if these limits are not enough for you, and we will evaluate\nincreasing them for your team.\n\n## On the models\n\nAfter this section you will find all the Spoke Public API endpoints available.\n\nEvery representation of resources that these endpoints create and return are\ndocumented in the [Models](/docs/category/models) page of the docs.\n" version: v0.2b servers: - url: https://api.spoke.com/public/v0.2b security: - BasicAuth: [] tags: - name: Stops description: 'Endpoints to operate on [Stop](/docs/models/stop) resources. For any [Plans](/docs/models/plan) created before 2023-04-01 the stop collections and all related operations will not be available. For any operations here you will need a Plan ID beforehand. You can retrieve an existing Plan by [listing your Plans](#tag/Plans/operation/listPlans) or you can [create a new one](#tag/Plans/operation/createPlan). ' paths: /plans/{planId}/stops: post: operationId: createStop summary: Create a new stop tags: - Stops description: Create a new stop with the given data. Prefer using the [batch import endpoint](#tag/Stops/operation/importStops) if you want to create multiple stops at once as it is more efficient and will produce better geocoding results. If the plan is not writable, this will fail, prefer using the [Live Create Stop API](#tag/Live-Stops/operation/createLiveStop) instead. requestBody: content: application/json: schema: 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 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' driver: description: 'Deprecated. Prefer using the `allowedDrivers` field instead. Driver ID that should be assigned to this stop. If not provided, the stop will be assigned to any available driver during optimization. This field is mutually exclusive with the `allowedDrivers` field.' anyOf: - type: string pattern: ^drivers\/[a-zA-Z0-9---_]{1,50}$ - type: 'null' allowedDrivers: description: Driver IDs that are allowed to be assigned to this stop. If not provided, the stop will be assigned to any available driver during optimization. This field is mutually exclusive with the `driver` field. When the stop is first created, all the drivers in this list will be added to the plan as well. If the stop is updated, no changes will be made to the plan, so if you want to add a driver to the plan, you must also add them to the plan separately, if they are not already. 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' circuitClientId: 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' required: - address additionalProperties: false required: true parameters: - schema: type: string pattern: ^[a-zA-Z0-9---_]{1,50}$ in: path name: planId required: true description: The plan id responses: '200': description: The created stop content: application/json: schema: $ref: '#/components/schemas/stopSchema' description: The created stop '400': description: The request has errors. Either syntactic or semantic content: application/json: schema: type: object properties: message: type: string description: The error message. code: type: string description: The error code. param: type: string description: The parameter that caused the error. url: type: string description: The URL with more information about the error. required: - message description: The request has errors. Either syntactic or semantic '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string description: The error message. url: type: string description: The URL with more information about the error. required: - message description: Unauthorized '403': description: The plan is no longer accessible or the stop contains fields that require upgrading your team subscription/settings. content: application/json: schema: oneOf: - type: object properties: message: type: string enum: - Plan is no longer accessible due to data access restrictions. Upgrade to a plan that supports a longer delivery history period to access it. code: type: string enum: - plan_inaccessible url: type: string enum: - https://dispatch.spoke.com/paywall required: - message - code - url description: Plan is no longer accessible due to data access restrictions. Upgrade to a plan that supports a longer delivery history period to access it. x-response-description: Plan is no longer accessible due to data access restrictions. Upgrade to a plan that supports a longer delivery history period to access it. - type: object properties: message: type: string description: The error message. code: type: string enum: - feature_not_in_subscription url: type: string enum: - https://dispatch.spoke.com/paywall required: - message - code - url description: Feature not included in your team subscription - type: object properties: message: type: string description: The error message. code: type: string enum: - vehicle_capacity_disabled url: type: string enum: - https://dispatch.spoke.com/settings/team-profile required: - message - code - url description: Vehicle capacity mode is disabled in the team's settings description: The plan is no longer accessible or the stop contains fields that require upgrading your team subscription/settings. '404': description: The plan or driver was not found content: application/json: schema: type: object properties: message: type: string description: The error message. required: - message description: The plan or driver was not found '409': description: The plan is not writable. content: application/json: schema: type: object properties: message: type: string enum: - Plan is not writable code: type: string enum: - plan_not_writable required: - message - code description: The plan is not writable. title: Plan is not writable '410': description: Failed to create stop content: application/json: schema: type: object properties: message: type: string enum: - Failed to create stop. Some related resources were deleted while the request was being processed. required: - message description: Failed to create stop '422': description: Failed to create stop content: application/json: schema: type: object properties: message: anyOf: - type: string enum: - An error occurred when creating the stop, but the error is not due to a validation error, instead it is another conflict, check if the provided data is semantically valid. - type: string required: - message description: Failed to create stop '500': description: An internal server error occurred content: application/json: schema: type: object properties: message: type: string description: The error message. code: type: string description: The error code. param: type: string description: The parameter that caused the error. url: type: string description: The URL with more information about the error. required: - message description: An internal server error occurred default: description: The default error model content: application/json: schema: type: object properties: message: type: string description: The error message. code: type: string description: The error code. param: type: string description: The parameter that caused the error. url: type: string description: The URL with more information about the error. required: - message description: The default error model get: operationId: listStops summary: List stops tags: - Stops parameters: - schema: type: string minLength: 1 maxLength: 255 in: query name: pageToken required: false description: The page token, if any. - schema: default: 10 type: number minimum: 1 maximum: 10 in: query name: maxPageSize required: false description: The max page size. - schema: type: object properties: externalId: description: Filter by the `recipient.externalId` field, exact match type: string minLength: 1 maxLength: 255 additionalProperties: false in: query name: filter required: false description: 'The filter to apply to the list of stops. The filter params are passed like this: `?filter[externalId]=foo` or like this: `?filter.externalId=foo`' - 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: stops: type: array items: $ref: '#/components/schemas/stopSchema' description: The stops list. nextPageToken: anyOf: - type: string - type: 'null' description: The next page token. required: - stops - nextPageToken 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//stops/`. 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. driverIdentifier: anyOf: - type: string - type: 'null' description: The driver identifier. This field is deprecated, prefer using `allowedDriversIdentifiers`. allowedDriversIdentifiers: type: array items: type: string description: The allowed drivers that can be assigned to this stop, replaces the `driverIdentifier` field. 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. 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 - 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. arrivedAt: anyOf: - type: number - type: 'null' description: When the driver arrived at the stop in seconds since epoch. This field is deprecated, prefer `timeAtStopInfo.arrivedAt`. timeAtStopInfo: anyOf: - 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 - type: 'null' description: Grouped time-at-stop data. timeAtStopInfoNullReason: anyOf: - type: object properties: reason: type: string enum: - subscription_not_supported message: type: string url: anyOf: - type: string - type: 'null' required: - reason - message - url - type: 'null' description: Reason why time-at-stop data was not provided. attemptedLocation: anyOf: - type: object properties: latitude: type: number description: The latitude of the location. longitude: type: number description: The longitude of the location. required: - latitude - longitude additionalProperties: false description: A location. - type: 'null' description: Where the stop was attempted. driverProvidedInternalNotes: anyOf: - type: string - type: 'null' description: Internal notes provided by the driver. driverProvidedRecipientNotes: anyOf: - type: string - type: 'null' description: Recipient notes provided by the driver. photoUrls: type: array items: type: string description: URLs of proof of delivery photos. recipientProvidedNotes: anyOf: - type: string - type: 'null' description: Notes from recipient signatureUrl: anyOf: - type: string - type: 'null' description: URL of the signature. signeeName: anyOf: - type: string - type: 'null' description: Name of the signee. succeeded: type: boolean description: Whether the stop was succeeded. state: type: string enum: - 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 description: The state of the delivery. required: - attempted - attemptedAt - arrivedAt - timeAtStopInfo - timeAtStopInfoNullReason - attemptedLocation - driverProvidedInternalNotes - driverProvidedRecipientNotes - photoUrls - recipientProvidedNotes - signatureUrl - signeeName - succeeded - state additionalProperties: false description: The delivery information of the stop. - type: 'null' paymentOnDelivery: anyOf: - type: object properties: amount: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' description: The amount *in minor units* (e.g. cents) to be collected upon delivery. currency: type: string description: The payment's currency in ISO 4217 standard. required: - amount - currency additionalProperties: false description: The payment due upon delivery also known as "Cash on Delivery". - type: 'null' proofOfAttemptRequirements: type: object properties: enabled: anyOf: - type: boolean - type: 'null' description: Whether the proof of attempt is enabled.This only works if the team subscription has access to proof of delivery required: - enabled additionalProperties: false description: The proof of attempt requirements of the stop. plan: type: string pattern: ^plans\/[a-zA-Z0-9---_]{1,50}$ description: The id of the plan, in the format `plans/`. route: anyOf: - type: object properties: id: type: string pattern: ^routes\/[a-zA-Z0-9---_]{1,50}$ description: The id of the route, in the format `routes/`. title: type: string description: The title of the route. stopCount: type: number description: The number of stops in the route. driver: anyOf: - type: string pattern: ^drivers\/[a-zA-Z0-9---_]{1,50}$ - type: 'null' description: The id of the driver. state: anyOf: - type: object properties: completed: type: boolean description: Whether the route is completed. completedAt: anyOf: - type: number - type: 'null' description: The timestamp the route was completed at. distributed: type: boolean description: Whether the route is distributed. distributedAt: anyOf: - type: number - type: 'null' description: The timestamp the route was distributed at. notifiedRecipients: type: boolean description: Whether the recipients were notified. notifiedRecipientsAt: anyOf: - type: number - type: 'null' description: The timestamp the recipients were notified at. started: type: boolean description: Whether the route is started. startedAt: anyOf: - type: number - type: 'null' description: The timestamp the route was started at. required: - completed - completedAt - distributed - distributedAt - notifiedRecipients - notifiedRecipientsAt - started - startedAt additionalProperties: false description: The state of a route. - type: 'null' description: The state of the route. plan: anyOf: - type: string pattern: ^plans\/[a-zA-Z0-9---_]{1,50}$ - type: 'null' description: The id of the related plan. required: - id - title - stopCount - driver - state - plan additionalProperties: false description: A route. - type: 'null' description: The route of the stop, if any. eta: anyOf: - type: object properties: estimatedArrivalAt: type: number description: The estimated time in seconds since epoch. estimatedLatestArrivalAt: type: number description: The latest estimated time in seconds since epoch. estimatedEarliestArrivalAt: type: number description: The earliest estimated time in seconds since epoch. required: - estimatedArrivalAt - estimatedLatestArrivalAt - estimatedEarliestArrivalAt additionalProperties: false description: The estimated time of arrival data of the stop. - type: 'null' etaNullReason: anyOf: - type: object properties: reason: type: string enum: - not_optimized - subscription_not_supported message: type: string url: anyOf: - type: string - type: 'null' required: - reason - message - url additionalProperties: false description: The reason why the ETA data is null, if it is. - type: 'null' timing: type: object properties: estimatedAttemptDuration: anyOf: - type: number - type: 'null' description: Time that the driver estimates to spend on the stop to do his job (deliver a parcel, visit a client, etc) in seconds. earliestAttemptTime: anyOf: - type: object properties: hour: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Hour of the day minute: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Minute of the hour required: - hour - minute additionalProperties: false description: Time of day in hours and minutes. Uses a 24 hour clock. - type: 'null' description: The earliest time that the driver should arrive at the stop latestAttemptTime: anyOf: - type: object properties: hour: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Hour of the day minute: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Minute of the hour required: - hour - minute additionalProperties: false description: Time of day in hours and minutes. Uses a 24 hour clock. - type: 'null' description: The latest time that the driver should arrive at the stop. required: - estimatedAttemptDuration - earliestAttemptTime - latestAttemptTime additionalProperties: false description: The timing data of the stop. optimizationOrder: default: default type: string enum: - first - last - default customProperties: anyOf: - type: object propertyNames: type: string additionalProperties: anyOf: - type: string - type: 'null' - type: 'null' description: Custom properties of the stop, can be used to store additional information. circuitClientId: anyOf: - type: string - type: 'null' description: The associated Client ID of the Spoke Connect required: - id - address - barcodes - driverIdentifier - allowedDriversIdentifiers - estimatedTravelDuration - estimatedTravelDistance - notes - packageCount - weight - type - packageLabel - stopPosition - trackingLink - webAppLink - orderInfo - placeInVehicle - recipient - deliveryInfo - paymentOnDelivery - proofOfAttemptRequirements - plan - route - eta - etaNullReason - timing - customProperties - circuitClientId additionalProperties: false description: A stop of a plan, can be related to a route. description: Success '400': description: Query parameters are invalid content: application/json: schema: type: object properties: message: type: string description: The error message. code: type: string description: The error code. param: type: string description: The parameter that caused the error. url: type: string description: The URL with more information about the error. required: - message description: Query parameters are invalid '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string description: The error message. url: type: string description: The URL with more information about the error. required: - message description: Unauthorized '403': description: Plan is no longer accessible due to data access restrictions. Upgrade to a plan that supports a longer delivery history period to access it. content: application/json: schema: type: object properties: message: type: string enum: - Plan is no longer accessible due to data access restrictions. Upgrade to a plan that supports a longer delivery history period to access it. code: type: string enum: - plan_inaccessible url: type: string enum: - https://dispatch.spoke.com/paywall required: - message - code - url description: 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': description: The provided plan id does not exist content: application/json: schema: type: object properties: message: type: string enum: - Plan not found required: - message description: The provided plan id does not exist title: Plan not found '500': description: An internal server error occurred content: application/json: schema: type: object properties: message: type: string description: The error message. code: type: string description: The error code. param: type: string description: The parameter that caused the error. url: type: string description: The URL with more information about the error. required: - message description: An internal server error occurred default: description: The default error model content: application/json: schema: type: object properties: message: type: string description: The error message. code: type: string description: The error code. param: type: string description: The parameter that caused the error. url: type: string description: The URL with more information about the error. required: - message description: The default error model /plans/{planId}/stops:import: post: operationId: importStops summary: Batch import stops tags: - Stops description: Batch import stops. The request body must contain an array of stops to import. If the plan is not writable, the request will fail, prefer using the [Import Live Stops API](#tag/Live-Stops/operation/importLiveStops) instead. requestBody: content: application/json: schema: description: An array of stops to import in batch. Supports a maximum of 100 stops per request. minItems: 1 maxItems: 100 type: array items: 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 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' driver: description: 'Deprecated. Prefer using the `allowedDrivers` field instead. Driver ID that should be assigned to this stop. If not provided, the stop will be assigned to any available driver during optimization. This field is mutually exclusive with the `allowedDrivers` field.' anyOf: - type: string pattern: ^drivers\/[a-zA-Z0-9---_]{1,50}$ - type: 'null' allowedDrivers: description: Driver IDs that are allowed to be assigned to this stop. If not provided, the stop will be assigned to any available driver during optimization. This field is mutually exclusive with the `driver` field. When the stop is first created, all the drivers in this list will be added to the plan as well. If the stop is updated, no changes will be made to the plan, so if you want to add a driver to the plan, you must also add them to the plan separately, if they are not already. 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' circuitClientId: 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' required: - address additionalProperties: false description: An array of stops to import in batch. Supports a maximum of 100 stops per request. 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: success: type: array items: 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//stops/`. description: The ids of the successfully imported stops failed: type: array items: type: object properties: error: type: object properties: message: type: string description: The error that occurred during import required: - message stop: type: object properties: address: type: object properties: addressName: anyOf: - type: string minLength: 1 maxLength: 255 - type: 'null' description: The name of the address. This will not be used for geocoding, and is only for the final address display purposes. addressLineOne: anyOf: - type: string minLength: 1 maxLength: 255 - type: 'null' description: The first line of the address. addressLineTwo: anyOf: - type: string minLength: 1 maxLength: 255 - type: 'null' description: The second line of the address. city: anyOf: - type: string minLength: 1 maxLength: 100 - type: 'null' description: The city of the address. state: anyOf: - type: string minLength: 1 maxLength: 100 - type: 'null' description: The state of the address. zip: anyOf: - type: string minLength: 1 maxLength: 100 - type: 'null' description: The zip code of the address. country: anyOf: - type: string minLength: 1 maxLength: 100 - type: 'null' description: The country 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. required: - addressName - addressLineOne - addressLineTwo - city - state - zip - country - latitude - longitude additionalProperties: false description: The address of the stop that failed to import recipient: anyOf: - type: object properties: externalId: anyOf: - type: string minLength: 1 maxLength: 255 - type: 'null' description: External ID of the recipient, as defined by the API user email: anyOf: - type: string minLength: 1 maxLength: 255 - type: 'null' description: Email of the recipient phone: anyOf: - type: string minLength: 1 maxLength: 255 - type: 'null' description: Phone number of the recipient name: anyOf: - type: string minLength: 1 maxLength: 255 - type: 'null' description: Name of the recipient required: - externalId - email - phone - name additionalProperties: false - type: 'null' description: The recipient of the stop that failed to import required: - address - recipient description: The stop that failed to import required: - error - stop description: The failed stops required: - success - failed description: Success '400': description: The request has errors. Either syntactic or semantic content: application/json: schema: type: object properties: message: type: string description: The error message. code: type: string description: The error code. param: type: string description: The parameter that caused the error. url: type: string description: The URL with more information about the error. required: - message description: The request has errors. Either syntactic or semantic '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string description: The error message. url: type: string description: The URL with more information about the error. required: - message description: Unauthorized '403': description: The plan is no longer accessible or one or more stops contain fields that require upgrading your team subscription/settings. content: application/json: schema: oneOf: - type: object properties: message: type: string enum: - Plan is no longer accessible due to data access restrictions. Upgrade to a plan that supports a longer delivery history period to access it. code: type: string enum: - plan_inaccessible url: type: string enum: - https://dispatch.spoke.com/paywall required: - message - code - url description: Plan is no longer accessible due to data access restrictions. Upgrade to a plan that supports a longer delivery history period to access it. x-response-description: Plan is no longer accessible due to data access restrictions. Upgrade to a plan that supports a longer delivery history period to access it. - type: object properties: message: type: string description: The error message. code: type: string enum: - feature_not_in_subscription url: type: string enum: - https://dispatch.spoke.com/paywall required: - message - code - url description: Feature not included in your team subscription - type: object properties: message: type: string description: The error message. code: type: string enum: - vehicle_capacity_disabled url: type: string enum: - https://dispatch.spoke.com/settings/team-profile required: - message - code - url description: Vehicle capacity mode is disabled in the team's settings description: The plan is no longer accessible or one or more stops contain fields that require upgrading your team subscription/settings. '404': description: A plan or a driver was not found content: application/json: schema: type: object properties: message: type: string description: The error message. required: - message description: A plan or a driver was not found '409': description: The plan is not writable. content: application/json: schema: type: object properties: message: type: string enum: - Plan is not writable code: type: string enum: - plan_not_writable required: - message - code description: The plan is not writable. title: Plan is not writable '410': description: Failed to create stop content: application/json: schema: type: object properties: message: type: string enum: - Failed to create stop. Some related resources were deleted while the request was being processed. required: - message description: Failed to create stop '422': description: Failed to create stop content: application/json: schema: type: object properties: message: anyOf: - type: string enum: - An error occurred when creating the stop, but the error is not due to a validation error, instead it is another conflict, check if the provided data is semantically valid. - type: string required: - message description: Failed to create stop '500': description: An internal server error occurred content: application/json: schema: type: object properties: message: type: string description: The error message. code: type: string description: The error code. param: type: string description: The parameter that caused the error. url: type: string description: The URL with more information about the error. required: - message description: An internal server error occurred default: description: The default error model content: application/json: schema: type: object properties: message: type: string description: The error message. code: type: string description: The error code. param: type: string description: The parameter that caused the error. url: type: string description: The URL with more information about the error. required: - message description: The default error model /plans/{planId}/stops/{stopId}: patch: operationId: updateStop summary: Update an existing stop tags: - Stops description: Does not support updating a stop's location, nor the `circuitClientId`. To do so, delete the stop and create a new one. If the plan is not writable, the request will fail, prefer using the [Update Live Stops API](#tag/Live-Stops/operation/updateLiveStop) instead. requestBody: content: application/json: schema: type: object properties: 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 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' driver: description: 'Deprecated. Prefer using the `allowedDrivers` field instead. Driver ID that should be assigned to this stop. If not provided, the stop will be assigned to any available driver during optimization. This field is mutually exclusive with the `allowedDrivers` field.' anyOf: - type: string pattern: ^drivers\/[a-zA-Z0-9---_]{1,50}$ - type: 'null' allowedDrivers: description: Driver IDs that are allowed to be assigned to this stop. If not provided, the stop will be assigned to any available driver during optimization. This field is mutually exclusive with the `driver` field. When the stop is first created, all the drivers in this list will be added to the plan as well. If the stop is updated, no changes will be made to the plan, so if you want to add a driver to the plan, you must also add them to the plan separately, if they are not already. 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' 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' timing: anyOf: - 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' additionalProperties: false parameters: - schema: type: string pattern: ^[a-zA-Z0-9---_]{1,50}$ in: path name: planId required: true description: The plan id - schema: type: string pattern: ^[a-zA-Z0-9---_]{1,50}$ in: path name: stopId required: true description: The stop id responses: '200': description: The updated stop content: application/json: schema: $ref: '#/components/schemas/stopSchema' description: The updated stop '400': description: The request has errors. Either syntactic or semantic content: application/json: schema: type: object properties: message: type: string description: The error message. code: type: string description: The error code. param: type: string description: The parameter that caused the error. url: type: string description: The URL with more information about the error. required: - message description: The request has errors. Either syntactic or semantic title: The request is invalid '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string description: The error message. url: type: string description: The URL with more information about the error. required: - message description: Unauthorized '403': description: The plan is no longer accessible or the stop contains fields that require upgrading your team subscription/settings. content: application/json: schema: oneOf: - type: object properties: message: type: string enum: - Plan is no longer accessible due to data access restrictions. Upgrade to a plan that supports a longer delivery history period to access it. code: type: string enum: - plan_inaccessible url: type: string enum: - https://dispatch.spoke.com/paywall required: - message - code - url description: Plan is no longer accessible due to data access restrictions. Upgrade to a plan that supports a longer delivery history period to access it. x-response-description: Plan is no longer accessible due to data access restrictions. Upgrade to a plan that supports a longer delivery history period to access it. - type: object properties: message: type: string description: The error message. code: type: string enum: - feature_not_in_subscription url: type: string enum: - https://dispatch.spoke.com/paywall required: - message - code - url description: Feature not included in your team subscription - type: object properties: message: type: string description: The error message. code: type: string enum: - vehicle_capacity_disabled url: type: string enum: - https://dispatch.spoke.com/settings/team-profile required: - message - code - url description: Vehicle capacity mode is disabled in the team's settings description: The plan is no longer accessible or the stop contains fields that require upgrading your team subscription/settings. '404': description: Not Found content: application/json: schema: type: object properties: message: type: string description: The error message. required: - message description: Not Found '409': description: The plan is not writable. content: application/json: schema: type: object properties: message: type: string enum: - Plan is not writable code: type: string enum: - plan_not_writable required: - message - code description: The plan is not writable. title: Plan is not writable '500': description: An internal server error occurred content: application/json: schema: type: object properties: message: type: string description: The error message. code: type: string description: The error code. param: type: string description: The parameter that caused the error. url: type: string description: The URL with more information about the error. required: - message description: An internal server error occurred default: description: The default error model content: application/json: schema: type: object properties: message: type: string description: The error message. code: type: string description: The error code. param: type: string description: The parameter that caused the error. url: type: string description: The URL with more information about the error. required: - message description: The default error model get: operationId: getStop summary: Retrieve a stop tags: - Stops description: Retrieve a stop parameters: - schema: type: string pattern: ^[a-zA-Z0-9---_]{1,50}$ in: path name: planId required: true description: The plan id - schema: type: string pattern: ^[a-zA-Z0-9---_]{1,50}$ in: path name: stopId required: true description: The stop id responses: '200': description: The requested stop content: application/json: schema: $ref: '#/components/schemas/stopSchema' description: The requested stop '400': description: ID format is invalid content: application/json: schema: type: object properties: message: type: string description: The error message. code: type: string description: The error code. param: type: string description: The parameter that caused the error. url: type: string description: The URL with more information about the error. required: - message description: ID format is invalid title: The request is invalid '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string description: The error message. url: type: string description: The URL with more information about the error. required: - message description: Unauthorized '403': description: Plan is no longer accessible due to data access restrictions. Upgrade to a plan that supports a longer delivery history period to access it. content: application/json: schema: type: object properties: message: type: string enum: - Plan is no longer accessible due to data access restrictions. Upgrade to a plan that supports a longer delivery history period to access it. code: type: string enum: - plan_inaccessible url: type: string enum: - https://dispatch.spoke.com/paywall required: - message - code - url description: 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': description: Not Found content: application/json: schema: type: object properties: message: type: string description: The error message. required: - message description: Not Found '500': description: An internal server error occurred content: application/json: schema: type: object properties: message: type: string description: The error message. code: type: string description: The error code. param: type: string description: The parameter that caused the error. url: type: string description: The URL with more information about the error. required: - message description: An internal server error occurred default: description: The default error model content: application/json: schema: type: object properties: message: type: string description: The error message. code: type: string description: The error code. param: type: string description: The parameter that caused the error. url: type: string description: The URL with more information about the error. required: - message description: The default error model delete: operationId: deleteStop summary: Delete a stop tags: - Stops description: Delete a stop. This action cannot be undone and will delete all the data associated with the stop. If the plan is not writable, this will fail, prefer using the [Live Delete Stop API](#tag/Live-Stops/operation/deleteLiveStop) instead. parameters: - schema: type: string pattern: ^[a-zA-Z0-9---_]{1,50}$ in: path name: planId required: true description: The plan id - schema: type: string pattern: ^[a-zA-Z0-9---_]{1,50}$ in: path name: stopId required: true description: The stop id responses: '204': description: Stop deleted successfully '400': description: ID format is invalid content: application/json: schema: type: object properties: message: type: string description: The error message. code: type: string description: The error code. param: type: string description: The parameter that caused the error. url: type: string description: The URL with more information about the error. required: - message description: ID format is invalid title: The request is invalid '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string description: The error message. url: type: string description: The URL with more information about the error. required: - message description: Unauthorized '403': description: Plan is no longer accessible due to data access restrictions. Upgrade to a plan that supports a longer delivery history period to access it. content: application/json: schema: type: object properties: message: type: string enum: - Plan is no longer accessible due to data access restrictions. Upgrade to a plan that supports a longer delivery history period to access it. code: type: string enum: - plan_inaccessible url: type: string enum: - https://dispatch.spoke.com/paywall required: - message - code - url description: 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': description: Not Found content: application/json: schema: type: object properties: message: type: string description: The error message. required: - message description: Not Found '409': description: The plan is not writable. content: application/json: schema: type: object properties: message: type: string enum: - Plan is not writable code: type: string enum: - plan_not_writable required: - message - code description: The plan is not writable. title: Plan is not writable '500': description: An internal server error occurred content: application/json: schema: type: object properties: message: type: string description: The error message. code: type: string description: The error code. param: type: string description: The parameter that caused the error. url: type: string description: The URL with more information about the error. required: - message description: An internal server error occurred default: description: The default error model content: application/json: schema: type: object properties: message: type: string description: The error message. code: type: string description: The error code. param: type: string description: The parameter that caused the error. url: type: string description: The URL with more information about the error. required: - message description: The default error model /stops:search: get: operationId: searchStops summary: Stop Search tags: - Stops description: "See the [Stops Search docs](/api/v1#section/Using-the-API/Stop-Search-API) for more information on formatting the filter string.\n The following fields are filterable:\n - `planId` - The ID of the plan stop is linked to in PlanId format (e.g. `plans/{planId}`)\n - `routeId` - The ID of the route stop is linked to in RouteId format (e.g. `routes/{routeId}`)\n - `type` - The type of the stop (e.g. `start`, `stop`, `end`)\n - `activity` - The activity performed at the stop (`delivery` or `pickup`)\n - `notes` - Notes associated with the stop\n - `orderInfo.sellerOrderId` - The order ID from the seller\n - `orderInfo.invoiceNumber` - The invoice number of the order\n - `orderInfo.sellerWebsite` - The website URL of the seller\n - `address.address` - The full address of the stop\n - `address.addressLineOne` - The first line of the stop address\n - `address.addressLineTwo` - The second line of the stop address\n - `address.latitude` - The latitude of the stop address in decimal degrees\n - `address.longitude` - The longitude of the stop address in decimal degrees\n - `address.placeId` - The Google Places identifier for the address\n - `address.countryCode` - The ISO country code for the address\n - `createdAt` - The timestamp when the stop was created (ISO 8601)\n - `arrivalAt` - The timestamp of the (estimated) arrival at the stop (ISO 8601)\n - `packageCount` - The number of packages to be delivered or picked up\n - `estimatedTravelDuration` - The estimated travel time to this stop from the previous one, in seconds\n - `estimatedTravelDistance` - The estimated travel distance to this stop from the previous one, in meters\n - `timing.estimatedAttemptDuration` - The estimated time spent at the stop to perform the activity, in seconds\n - `recipient.name` - The name of the recipient at the stop\n - `recipient.email` - The email address of the recipient\n - `recipient.phone` - The phone number of the recipient\n - `recipient.externalId` - An external identifier for the recipient\n - `deliveryInfo.state` - The current state of the delivery (e.g. `delivered_to_recipient`, `failed_not_home`)\n - `deliveryInfo.attempted` - Whether a delivery attempt has been made\n - `deliveryInfo.succeeded` - Whether the delivery was successful\n - `deliveryInfo.recipientProvidedNotes` - Notes provided by the recipient for the driver\n - `deliveryInfo.driverProvidedInternalNotes` - Internal notes provided by the driver\n - `deliveryInfo.driverProvidedRecipientNotes` - Notes for the recipient provided by the driver\n - `deliveryInfo.signeeName` - The name of the person who signed for the delivery\n - `deliveryInfo.attemptedAt` - The timestamp when the delivery was attempted (ISO 8601)\n - `orderInfo.products` - The list of products included in the order\n - `orderInfo.sellerName` - The name of the seller\n - `paymentOnDelivery.amount` - The amount to be collected on delivery, in original units\n - `barcodes` - The list of barcodes associated with the stop\n - `packageLabel` - The label applied to the package(s)\n - `customProperties.*` - A custom property of the stop. Replace `*` with the custom property ID.\n\n The following fields are sortable:\n - `address.latitude`\n - `address.longitude`\n - `createdAt`\n - `arrivalAt`\n - `packageCount`\n - `estimatedTravelDuration`\n - `estimatedTravelDistance`\n - `timing.estimatedAttemptDuration`\n - `deliveryInfo.attemptedAt`\n - `paymentOnDelivery.amount`\n" parameters: - schema: type: string minLength: 1 maxLength: 255 in: query name: keyword required: false description: Keywords to include in the search. These will be applied to all applicable text fields using a fuzzy matching. - schema: type: string minLength: 1 maxLength: 2048 in: query name: filter required: false description: The filter to apply. This is used to include/exclude stops form the search. - schema: type: string in: query name: pageToken required: false description: The page token. - schema: default: 20 type: integer exclusiveMinimum: 1 exclusiveMaximum: 20 in: query name: maxPageSize required: false description: The max page size. - schema: type: string in: query name: sortField required: false description: The sort field. - schema: default: asc type: string enum: - asc - desc in: query name: sortOrder required: false description: The sort direction. responses: '200': description: Success content: application/json: schema: type: object properties: stops: type: array items: oneOf: - type: object properties: type: type: string description: The type of the stop. enum: - stop stop: allOf: - $ref: '#/components/schemas/stopSchema_2' description: The stop. required: - type - stop - type: object properties: type: type: string description: The type of the stop. enum: - unassignedStop unassignedStop: allOf: - $ref: '#/components/schemas/unassignedStopSchema' description: The unassigned stop. required: - type - unassignedStop description: The stops list. nextPageToken: anyOf: - type: string - type: 'null' description: The next page token. required: - stops - nextPageToken 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//stops/`. 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 requiredFeature: type: string upgradeUrl: type: string restrictionCode: type: string enum: - subscription_not_supported required: - status additionalProperties: false - type: object properties: status: type: string enum: - pending pendingReason: type: string enum: - not_yet_arrived required: - status additionalProperties: false attemptedLocation: anyOf: - type: object properties: latitude: type: number description: The latitude of the location. longitude: type: number description: The longitude of the location. required: - latitude - longitude additionalProperties: false description: A location. - type: 'null' description: Where the stop was attempted. driverProvidedInternalNotes: anyOf: - type: string - type: 'null' description: Internal notes provided by the driver. driverProvidedRecipientNotes: anyOf: - type: string - type: 'null' description: Recipient notes provided by the driver. photoUrls: type: array items: type: string description: URLs of proof of delivery photos. recipientProvidedNotes: anyOf: - type: string - type: 'null' description: Notes from recipient signatureUrl: anyOf: - type: string - type: 'null' description: URL of the signature. signeeName: anyOf: - type: string - type: 'null' description: Name of the signee. succeeded: type: boolean description: Whether the stop was succeeded. state: type: string enum: - 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 description: The state of the delivery. required: - attempted - attemptedAt - timeAtStopInfo - attemptedLocation - driverProvidedInternalNotes - driverProvidedRecipientNotes - photoUrls - recipientProvidedNotes - signatureUrl - signeeName - succeeded - state additionalProperties: false description: The delivery information of the stop. - type: 'null' paymentOnDelivery: anyOf: - type: object properties: amount: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' description: The amount *in minor units* (e.g. cents) to be collected upon delivery. currency: type: string description: The payment's currency in ISO 4217 standard. required: - amount - currency additionalProperties: false description: The payment due upon delivery also known as "Cash on Delivery". - type: 'null' proofOfAttemptRequirements: type: object properties: enabled: anyOf: - type: boolean - type: 'null' description: Whether the proof of attempt is enabled.This only works if the team subscription has access to proof of delivery required: - enabled additionalProperties: false description: The proof of attempt requirements of the stop. plan: type: string pattern: ^plans\/[a-zA-Z0-9---_]{1,50}$ description: The id of the plan, in the format `plans/`. route: anyOf: - type: object properties: id: type: string pattern: ^routes\/[a-zA-Z0-9---_]{1,50}$ description: The id of the route, in the format `routes/`. title: type: string description: The title of the route. stopCount: type: number description: The number of stops in the route. driver: anyOf: - type: string pattern: ^drivers\/[a-zA-Z0-9---_]{1,50}$ - type: 'null' description: The id of the driver. state: anyOf: - type: object properties: completed: type: boolean description: Whether the route is completed. completedAt: anyOf: - type: number - type: 'null' description: The timestamp the route was completed at. distributed: type: boolean description: Whether the route is distributed. distributedAt: anyOf: - type: number - type: 'null' description: The timestamp the route was distributed at. notifiedRecipients: type: boolean description: Whether the recipients were notified. notifiedRecipientsAt: anyOf: - type: number - type: 'null' description: The timestamp the recipients were notified at. started: type: boolean description: Whether the route is started. startedAt: anyOf: - type: number - type: 'null' description: The timestamp the route was started at. required: - completed - completedAt - distributed - distributedAt - notifiedRecipients - notifiedRecipientsAt - started - startedAt additionalProperties: false description: The state of a route. - type: 'null' description: The state of the route. plan: anyOf: - type: string pattern: ^plans\/[a-zA-Z0-9---_]{1,50}$ - type: 'null' description: The id of the related plan. required: - id - title - stopCount - driver - state - plan additionalProperties: false description: A route. - type: 'null' description: The route of the stop, if any. eta: oneOf: - type: object properties: status: type: string enum: - available value: type: object properties: estimatedArrivalAt: type: number description: The estimated time in seconds since epoch. estimatedLatestArrivalAt: type: number description: The latest estimated time in seconds since epoch. estimatedEarliestArrivalAt: type: number description: The earliest estimated time in seconds since epoch. required: - estimatedArrivalAt - estimatedLatestArrivalAt - estimatedEarliestArrivalAt additionalProperties: false description: The estimated time of arrival data of the stop. required: - status - value additionalProperties: false - type: object properties: status: type: string enum: - restricted requiredFeature: type: string upgradeUrl: type: string restrictionCode: type: string enum: - subscription_not_supported required: - status additionalProperties: false - type: object properties: status: type: string enum: - pending pendingReason: type: string enum: - not_optimized required: - status additionalProperties: false timing: type: object properties: estimatedAttemptDuration: anyOf: - type: number - type: 'null' description: Time that the driver estimates to spend on the stop to do his job (deliver a parcel, visit a client, etc) in seconds. earliestAttemptTime: anyOf: - type: object properties: hour: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Hour of the day minute: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Minute of the hour required: - hour - minute additionalProperties: false description: Time of day in hours and minutes. Uses a 24 hour clock. - type: 'null' description: The earliest time that the driver should arrive at the stop latestAttemptTime: anyOf: - type: object properties: hour: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Hour of the day minute: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Minute of the hour required: - hour - minute additionalProperties: false description: Time of day in hours and minutes. Uses a 24 hour clock. - type: 'null' description: The latest time that the driver should arrive at the stop. required: - estimatedAttemptDuration - earliestAttemptTime - latestAttemptTime additionalProperties: false description: The timing data of the stop. optimizationOrder: default: default type: string enum: - first - last - default customProperties: anyOf: - type: object propertyNames: type: string additionalProperties: anyOf: - type: string - type: 'null' - type: 'null' description: Custom properties of the stop, can be used to store additional information. clientId: anyOf: - type: string - type: 'null' description: The associated Client ID of the Spoke Connect serviceInfo: oneOf: - type: object properties: status: type: string enum: - available value: anyOf: - type: object properties: identifier: type: string description: The service offering identifier, as configured in Spoke Dispatch, captured at assignment time. Not currently discoverable through the public API. name: type: string description: The human-readable service name. slaStartsAt: type: number description: The SLA start time in seconds since epoch. slaDueDate: type: object properties: day: type: integer minimum: 1 maximum: 31 description: The day of the date. month: type: integer minimum: 1 maximum: 12 description: The month of the date. year: type: integer minimum: 2000 maximum: 2100 description: The year of the date. required: - day - month - year additionalProperties: false description: The computed SLA due date in the team's timezone. slaDueTime: anyOf: - type: object properties: hour: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Hour of the day minute: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Minute of the hour required: - hour - minute additionalProperties: false description: Time of day in hours and minutes. Uses a 24 hour clock. - type: 'null' description: SLA due time-of-day in the team's timezone, null for day-level SLA. deliveryHorizon: type: object properties: unit: anyOf: - type: string enum: - days - hours - type: string description: 'The time unit of the delivery horizon. Known: `days`, `hours`.' value: type: number description: The number of time units in the delivery horizon. required: - unit - value additionalProperties: false description: The delivery horizon for this service. price: type: object properties: value: type: number description: Price in minor currency units (e.g. cents). 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: string description: 3-letter ISO 4217 currency code. required: - value - currency additionalProperties: false description: Price for this service at assignment time. hasPaymentOnDelivery: type: boolean description: Whether cash on delivery is enabled via the service. definedAt: type: number description: When the service was assigned in seconds since epoch. required: - identifier - name - slaStartsAt - slaDueDate - slaDueTime - deliveryHorizon - price - hasPaymentOnDelivery - definedAt additionalProperties: false description: Service offering data when a service is assigned to the stop. - type: object properties: identifier: type: 'null' description: Null indicates no service offering is linked. slaStartsAt: type: number description: The SLA start time in seconds since epoch. required: - identifier - slaStartsAt additionalProperties: false description: Service data when only an SLA start time is set. description: Service offering data for this stop. required: - status - value additionalProperties: false - type: object properties: status: type: string enum: - empty required: - status additionalProperties: false - type: object properties: status: type: string enum: - restricted requiredFeature: type: string upgradeUrl: type: string restrictionCode: type: string enum: - subscription_not_supported required: - status additionalProperties: false description: Service offering data for this stop. required: - id - address - barcodes - allowedDrivers - estimatedTravelDuration - estimatedTravelDistance - notes - packageCount - weight - type - packageLabel - stopPosition - trackingLink - webAppLink - orderInfo - placeInVehicle - recipient - deliveryInfo - paymentOnDelivery - proofOfAttemptRequirements - plan - route - eta - timing - customProperties - clientId - serviceInfo additionalProperties: false unassignedStopSchema: type: object properties: id: type: string pattern: ^unassignedStops\/[a-zA-Z0-9---_]{1,50}$ description: The id of the unassigned stop, in the format `unassignedStops/`. depot: type: string pattern: ^depots\/[a-zA-Z0-9---_]{1,50}$ description: The depot that this unassigned stop belongs to. 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. 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' 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. 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 trackingLink: anyOf: - type: string - type: 'null' description: The recipient tracking link. timing: type: object properties: estimatedAttemptDuration: anyOf: - type: number - type: 'null' description: Time that the driver estimates to spend on the stop to do his job (deliver a parcel, visit a client, etc) in seconds. earliestAttemptTime: anyOf: - type: object properties: hour: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Hour of the day minute: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Minute of the hour required: - hour - minute additionalProperties: false description: Time of day in hours and minutes. Uses a 24 hour clock. - type: 'null' description: The earliest time that the driver should arrive at the stop latestAttemptTime: anyOf: - type: object properties: hour: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Hour of the day minute: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Minute of the hour required: - hour - minute additionalProperties: false description: Time of day in hours and minutes. Uses a 24 hour clock. - type: 'null' description: The latest time that the driver should arrive at the stop. required: - estimatedAttemptDuration - earliestAttemptTime - latestAttemptTime additionalProperties: false description: The timing data of the stop. optimizationOrder: default: default type: string enum: - first - last - default paymentOnDelivery: anyOf: - type: object properties: amount: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' description: The amount *in minor units* (e.g. cents) to be collected upon delivery. currency: type: string description: The payment's currency in ISO 4217 standard. required: - amount - currency additionalProperties: false description: The payment due upon delivery also known as "Cash on Delivery". - type: 'null' proofOfAttemptRequirements: type: object properties: enabled: anyOf: - type: boolean - type: 'null' description: Whether the proof of attempt is enabled.This only works if the team subscription has access to proof of delivery required: - enabled additionalProperties: false description: The proof of attempt requirements of the stop. customProperties: anyOf: - type: object propertyNames: type: string additionalProperties: anyOf: - type: string - type: 'null' - type: 'null' description: Custom properties of the stop, can be used to store additional information. clientId: anyOf: - type: string - type: 'null' description: The associated Client ID of the Spoke Connect required: - id - depot - address - barcodes - allowedDrivers - notes - packageCount - weight - orderInfo - recipient - trackingLink - timing - paymentOnDelivery - proofOfAttemptRequirements - customProperties - clientId additionalProperties: false description: Success '400': description: The request was invalid content: application/json: schema: oneOf: - type: object properties: message: type: string description: The error message. code: type: string description: The error code. param: type: string description: The parameter that caused the error. url: type: string description: The URL with more information about the error. required: - message description: The request has errors. Either syntactic or semantic - type: object properties: message: type: string code: type: string description: The error code. param: type: string enum: - filter url: type: string description: The URL with more information about the error. required: - message - param description: The provided filter string was invalid. title: Invalid filter string - type: object properties: message: type: string code: type: string description: The error code. param: type: string enum: - sortField url: type: string description: The URL with more information about the error. required: - message - param description: The provided sort field was unknown. title: Unknown sort field - type: object properties: message: type: string code: type: string description: The error code. param: type: string enum: - pageToken url: type: string description: The URL with more information about the error. required: - message - param description: The provided page token was invalid. title: Invalid page token description: The request was invalid '401': description: Unauthorized content: application/json: schema: type: object properties: message: type: string description: The error message. url: type: string description: The URL with more information about the error. required: - message description: Unauthorized '500': description: An internal server error occurred content: application/json: schema: type: object properties: message: type: string description: The error message. code: type: string description: The error code. param: type: string description: The parameter that caused the error. url: type: string description: The URL with more information about the error. required: - message description: An internal server error occurred default: description: The default error model content: application/json: schema: type: object properties: message: type: string description: The error message. code: type: string description: The error code. param: type: string description: The parameter that caused the error. url: type: string description: The URL with more information about the error. required: - message description: The default error model components: schemas: unassignedStopSchema: type: object properties: id: allOf: - $ref: '#/components/schemas/unassignedStopIdSchema' description: The id of the unassigned stop, in the format `unassignedStops/`. depot: type: string pattern: ^depots\/[a-zA-Z0-9---_]{1,50}$ description: The depot that this unassigned stop belongs to. 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. 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' 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. 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 trackingLink: anyOf: - type: string - type: 'null' description: The recipient tracking link. timing: type: object properties: estimatedAttemptDuration: anyOf: - type: number - type: 'null' description: Time that the driver estimates to spend on the stop to do his job (deliver a parcel, visit a client, etc) in seconds. earliestAttemptTime: anyOf: - $ref: '#/components/schemas/timeOfDaySchema' - type: 'null' description: The earliest time that the driver should arrive at the stop latestAttemptTime: anyOf: - $ref: '#/components/schemas/timeOfDaySchema' - type: 'null' description: The latest time that the driver should arrive at the stop. required: - estimatedAttemptDuration - earliestAttemptTime - latestAttemptTime additionalProperties: false description: The timing data of the stop. optimizationOrder: default: default type: string enum: - first - last - default paymentOnDelivery: anyOf: - type: object properties: amount: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' description: The amount *in minor units* (e.g. cents) to be collected upon delivery. currency: type: string description: The payment's currency in ISO 4217 standard. required: - amount - currency additionalProperties: false description: The payment due upon delivery also known as "Cash on Delivery". - type: 'null' proofOfAttemptRequirements: type: object properties: enabled: anyOf: - type: boolean - type: 'null' description: Whether the proof of attempt is enabled.This only works if the team subscription has access to proof of delivery required: - enabled additionalProperties: false description: The proof of attempt requirements of the stop. customProperties: anyOf: - type: object propertyNames: type: string additionalProperties: anyOf: - type: string - type: 'null' - type: 'null' description: Custom properties of the stop, can be used to store additional information. clientId: anyOf: - type: string - type: 'null' description: The associated Client ID of the Spoke Connect required: - id - depot - address - barcodes - allowedDrivers - notes - packageCount - weight - orderInfo - recipient - trackingLink - timing - paymentOnDelivery - proofOfAttemptRequirements - customProperties - clientId additionalProperties: false description: An unassigned stop. routeSchema: type: object properties: id: allOf: - $ref: '#/components/schemas/routeIdSchema' description: The id of the route, in the format `routes/`. title: type: string description: The title of the route. stopCount: type: number description: The number of stops in the route. driver: anyOf: - $ref: '#/components/schemas/driverIdSchema' - type: 'null' description: The id of the driver. state: anyOf: - type: object properties: completed: type: boolean description: Whether the route is completed. completedAt: anyOf: - type: number - type: 'null' description: The timestamp the route was completed at. distributed: type: boolean description: Whether the route is distributed. distributedAt: anyOf: - type: number - type: 'null' description: The timestamp the route was distributed at. notifiedRecipients: type: boolean description: Whether the recipients were notified. notifiedRecipientsAt: anyOf: - type: number - type: 'null' description: The timestamp the recipients were notified at. started: type: boolean description: Whether the route is started. startedAt: anyOf: - type: number - type: 'null' description: The timestamp the route was started at. required: - completed - completedAt - distributed - distributedAt - notifiedRecipients - notifiedRecipientsAt - started - startedAt additionalProperties: false description: The state of a route. - type: 'null' description: The state of the route. plan: anyOf: - $ref: '#/components/schemas/planIdSchema' - type: 'null' description: The id of the related plan. required: - id - title - stopCount - driver - state - plan additionalProperties: false description: A route. stopIdSchema: type: string pattern: ^plans\/[a-zA-Z0-9---_]{1,50}\/stops\/[a-zA-Z0-9---_]{1,50}$ stopSchema_2: type: object properties: id: allOf: - $ref: '#/components/schemas/stopIdSchema' description: The id of the stop, in the format `plans//stops/`. 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 requiredFeature: type: string upgradeUrl: type: string restrictionCode: type: string enum: - subscription_not_supported required: - status additionalProperties: false - type: object properties: status: type: string enum: - pending pendingReason: type: string enum: - not_yet_arrived required: - status additionalProperties: false attemptedLocation: anyOf: - type: object properties: latitude: type: number description: The latitude of the location. longitude: type: number description: The longitude of the location. required: - latitude - longitude additionalProperties: false description: A location. - type: 'null' description: Where the stop was attempted. driverProvidedInternalNotes: anyOf: - type: string - type: 'null' description: Internal notes provided by the driver. driverProvidedRecipientNotes: anyOf: - type: string - type: 'null' description: Recipient notes provided by the driver. photoUrls: type: array items: type: string description: URLs of proof of delivery photos. recipientProvidedNotes: anyOf: - type: string - type: 'null' description: Notes from recipient signatureUrl: anyOf: - type: string - type: 'null' description: URL of the signature. signeeName: anyOf: - type: string - type: 'null' description: Name of the signee. succeeded: type: boolean description: Whether the stop was succeeded. state: type: string enum: - 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 description: The state of the delivery. required: - attempted - attemptedAt - timeAtStopInfo - attemptedLocation - driverProvidedInternalNotes - driverProvidedRecipientNotes - photoUrls - recipientProvidedNotes - signatureUrl - signeeName - succeeded - state additionalProperties: false description: The delivery information of the stop. - type: 'null' paymentOnDelivery: anyOf: - type: object properties: amount: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' description: The amount *in minor units* (e.g. cents) to be collected upon delivery. currency: type: string description: The payment's currency in ISO 4217 standard. required: - amount - currency additionalProperties: false description: The payment due upon delivery also known as "Cash on Delivery". - type: 'null' proofOfAttemptRequirements: type: object properties: enabled: anyOf: - type: boolean - type: 'null' description: Whether the proof of attempt is enabled.This only works if the team subscription has access to proof of delivery required: - enabled additionalProperties: false description: The proof of attempt requirements of the stop. plan: allOf: - $ref: '#/components/schemas/planIdSchema' description: The id of the plan, in the format `plans/`. route: anyOf: - $ref: '#/components/schemas/routeSchema' - type: 'null' description: The route of the stop, if any. eta: oneOf: - type: object properties: status: type: string enum: - available value: type: object properties: estimatedArrivalAt: type: number description: The estimated time in seconds since epoch. estimatedLatestArrivalAt: type: number description: The latest estimated time in seconds since epoch. estimatedEarliestArrivalAt: type: number description: The earliest estimated time in seconds since epoch. required: - estimatedArrivalAt - estimatedLatestArrivalAt - estimatedEarliestArrivalAt additionalProperties: false description: The estimated time of arrival data of the stop. required: - status - value additionalProperties: false - type: object properties: status: type: string enum: - restricted requiredFeature: type: string upgradeUrl: type: string restrictionCode: type: string enum: - subscription_not_supported required: - status additionalProperties: false - type: object properties: status: type: string enum: - pending pendingReason: type: string enum: - not_optimized required: - status additionalProperties: false timing: type: object properties: estimatedAttemptDuration: anyOf: - type: number - type: 'null' description: Time that the driver estimates to spend on the stop to do his job (deliver a parcel, visit a client, etc) in seconds. earliestAttemptTime: anyOf: - $ref: '#/components/schemas/timeOfDaySchema' - type: 'null' description: The earliest time that the driver should arrive at the stop latestAttemptTime: anyOf: - $ref: '#/components/schemas/timeOfDaySchema' - type: 'null' description: The latest time that the driver should arrive at the stop. required: - estimatedAttemptDuration - earliestAttemptTime - latestAttemptTime additionalProperties: false description: The timing data of the stop. optimizationOrder: default: default type: string enum: - first - last - default customProperties: anyOf: - type: object propertyNames: type: string additionalProperties: anyOf: - type: string - type: 'null' - type: 'null' description: Custom properties of the stop, can be used to store additional information. clientId: anyOf: - type: string - type: 'null' description: The associated Client ID of the Spoke Connect serviceInfo: oneOf: - type: object properties: status: type: string enum: - available value: anyOf: - type: object properties: identifier: type: string description: The service offering identifier, as configured in Spoke Dispatch, captured at assignment time. Not currently discoverable through the public API. name: type: string description: The human-readable service name. slaStartsAt: type: number description: The SLA start time in seconds since epoch. slaDueDate: type: object properties: day: type: integer minimum: 1 maximum: 31 description: The day of the date. month: type: integer minimum: 1 maximum: 12 description: The month of the date. year: type: integer minimum: 2000 maximum: 2100 description: The year of the date. required: - day - month - year additionalProperties: false description: The computed SLA due date in the team's timezone. slaDueTime: anyOf: - $ref: '#/components/schemas/timeOfDaySchema' - type: 'null' description: SLA due time-of-day in the team's timezone, null for day-level SLA. deliveryHorizon: type: object properties: unit: anyOf: - type: string enum: - days - hours - type: string description: 'The time unit of the delivery horizon. Known: `days`, `hours`.' value: type: number description: The number of time units in the delivery horizon. required: - unit - value additionalProperties: false description: The delivery horizon for this service. price: type: object properties: value: type: number description: Price in minor currency units (e.g. cents). 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: string description: 3-letter ISO 4217 currency code. required: - value - currency additionalProperties: false description: Price for this service at assignment time. hasPaymentOnDelivery: type: boolean description: Whether cash on delivery is enabled via the service. definedAt: type: number description: When the service was assigned in seconds since epoch. required: - identifier - name - slaStartsAt - slaDueDate - slaDueTime - deliveryHorizon - price - hasPaymentOnDelivery - definedAt additionalProperties: false description: Service offering data when a service is assigned to the stop. - type: object properties: identifier: type: 'null' description: Null indicates no service offering is linked. slaStartsAt: type: number description: The SLA start time in seconds since epoch. required: - identifier - slaStartsAt additionalProperties: false description: Service data when only an SLA start time is set. description: Service offering data for this stop. required: - status - value additionalProperties: false - type: object properties: status: type: string enum: - empty required: - status additionalProperties: false - type: object properties: status: type: string enum: - restricted requiredFeature: type: string upgradeUrl: type: string restrictionCode: type: string enum: - subscription_not_supported required: - status additionalProperties: false description: Service offering data for this stop. required: - id - address - barcodes - allowedDrivers - estimatedTravelDuration - estimatedTravelDistance - notes - packageCount - weight - type - packageLabel - stopPosition - trackingLink - webAppLink - orderInfo - placeInVehicle - recipient - deliveryInfo - paymentOnDelivery - proofOfAttemptRequirements - plan - route - eta - timing - customProperties - clientId - serviceInfo additionalProperties: false description: A stop of a plan, can be related to a route. routeIdSchema: type: string pattern: ^routes\/[a-zA-Z0-9---_]{1,50}$ stopSchema: type: object properties: id: allOf: - $ref: '#/components/schemas/stopIdSchema' description: The id of the stop, in the format `plans//stops/`. 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. driverIdentifier: anyOf: - type: string - type: 'null' description: The driver identifier. This field is deprecated, prefer using `allowedDriversIdentifiers`. allowedDriversIdentifiers: type: array items: type: string description: The allowed drivers that can be assigned to this stop, replaces the `driverIdentifier` field. 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. 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 - 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. arrivedAt: anyOf: - type: number - type: 'null' description: When the driver arrived at the stop in seconds since epoch. This field is deprecated, prefer `timeAtStopInfo.arrivedAt`. timeAtStopInfo: anyOf: - 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 - type: 'null' description: Grouped time-at-stop data. timeAtStopInfoNullReason: anyOf: - type: object properties: reason: type: string enum: - subscription_not_supported message: type: string url: anyOf: - type: string - type: 'null' required: - reason - message - url - type: 'null' description: Reason why time-at-stop data was not provided. attemptedLocation: anyOf: - type: object properties: latitude: type: number description: The latitude of the location. longitude: type: number description: The longitude of the location. required: - latitude - longitude additionalProperties: false description: A location. - type: 'null' description: Where the stop was attempted. driverProvidedInternalNotes: anyOf: - type: string - type: 'null' description: Internal notes provided by the driver. driverProvidedRecipientNotes: anyOf: - type: string - type: 'null' description: Recipient notes provided by the driver. photoUrls: type: array items: type: string description: URLs of proof of delivery photos. recipientProvidedNotes: anyOf: - type: string - type: 'null' description: Notes from recipient signatureUrl: anyOf: - type: string - type: 'null' description: URL of the signature. signeeName: anyOf: - type: string - type: 'null' description: Name of the signee. succeeded: type: boolean description: Whether the stop was succeeded. state: type: string enum: - 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 description: The state of the delivery. required: - attempted - attemptedAt - arrivedAt - timeAtStopInfo - timeAtStopInfoNullReason - attemptedLocation - driverProvidedInternalNotes - driverProvidedRecipientNotes - photoUrls - recipientProvidedNotes - signatureUrl - signeeName - succeeded - state additionalProperties: false description: The delivery information of the stop. - type: 'null' paymentOnDelivery: anyOf: - type: object properties: amount: anyOf: - type: integer minimum: 0 maximum: 9007199254740991 - type: 'null' description: The amount *in minor units* (e.g. cents) to be collected upon delivery. currency: type: string description: The payment's currency in ISO 4217 standard. required: - amount - currency additionalProperties: false description: The payment due upon delivery also known as "Cash on Delivery". - type: 'null' proofOfAttemptRequirements: type: object properties: enabled: anyOf: - type: boolean - type: 'null' description: Whether the proof of attempt is enabled.This only works if the team subscription has access to proof of delivery required: - enabled additionalProperties: false description: The proof of attempt requirements of the stop. plan: allOf: - $ref: '#/components/schemas/planIdSchema' description: The id of the plan, in the format `plans/`. route: anyOf: - $ref: '#/components/schemas/routeSchema' - type: 'null' description: The route of the stop, if any. eta: anyOf: - type: object properties: estimatedArrivalAt: type: number description: The estimated time in seconds since epoch. estimatedLatestArrivalAt: type: number description: The latest estimated time in seconds since epoch. estimatedEarliestArrivalAt: type: number description: The earliest estimated time in seconds since epoch. required: - estimatedArrivalAt - estimatedLatestArrivalAt - estimatedEarliestArrivalAt additionalProperties: false description: The estimated time of arrival data of the stop. - type: 'null' etaNullReason: anyOf: - type: object properties: reason: type: string enum: - not_optimized - subscription_not_supported message: type: string url: anyOf: - type: string - type: 'null' required: - reason - message - url additionalProperties: false description: The reason why the ETA data is null, if it is. - type: 'null' timing: type: object properties: estimatedAttemptDuration: anyOf: - type: number - type: 'null' description: Time that the driver estimates to spend on the stop to do his job (deliver a parcel, visit a client, etc) in seconds. earliestAttemptTime: anyOf: - $ref: '#/components/schemas/timeOfDaySchema' - type: 'null' description: The earliest time that the driver should arrive at the stop latestAttemptTime: anyOf: - $ref: '#/components/schemas/timeOfDaySchema' - type: 'null' description: The latest time that the driver should arrive at the stop. required: - estimatedAttemptDuration - earliestAttemptTime - latestAttemptTime additionalProperties: false description: The timing data of the stop. optimizationOrder: default: default type: string enum: - first - last - default customProperties: anyOf: - type: object propertyNames: type: string additionalProperties: anyOf: - type: string - type: 'null' - type: 'null' description: Custom properties of the stop, can be used to store additional information. circuitClientId: anyOf: - type: string - type: 'null' description: The associated Client ID of the Spoke Connect required: - id - address - barcodes - driverIdentifier - allowedDriversIdentifiers - estimatedTravelDuration - estimatedTravelDistance - notes - packageCount - weight - type - packageLabel - stopPosition - trackingLink - webAppLink - orderInfo - placeInVehicle - recipient - deliveryInfo - paymentOnDelivery - proofOfAttemptRequirements - plan - route - eta - etaNullReason - timing - customProperties - circuitClientId additionalProperties: false description: A stop of a plan, can be related to a route. timeOfDaySchema: type: object properties: hour: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Hour of the day minute: type: integer minimum: -9007199254740991 maximum: 9007199254740991 description: Minute of the hour required: - hour - minute additionalProperties: false description: Time of day in hours and minutes. Uses a 24 hour clock. planIdSchema: type: string pattern: ^plans\/[a-zA-Z0-9---_]{1,50}$ driverIdSchema: type: string pattern: ^drivers\/[a-zA-Z0-9---_]{1,50}$ unassignedStopIdSchema: type: string pattern: ^unassignedStops\/[a-zA-Z0-9---_]{1,50}$ securitySchemes: BasicAuth: type: http scheme: basic description: Use the API key as the username and leave the password empty.