{ "openapi": "3.1.0", "info": { "title": "Spoke 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# v1 Migration Guide\n\nIf migrating from version 0.2b to v1, please note the following changes.\n\n### General\n\n1. Only `api.spoke.com` should be used for the `v1` API.\n2. Webhooks requests will now only contain the `spoke-signature` header.\n\n### Stops\n\nRemovals:\n\n| Operation | 0.2b Property | v1 Property | Notes |\n| ---------- | ------------------------------- | -------------------------------- | ---------------------------------------------------------------------------- |\n| WRITE | `stop.driver` | `stop.allowedDrivers` | Drivers should now be provided as an array of `DriverIds`. |\n| READ | `stop.driverIdentifier` | `stop.allowedDrivers` | Drivers will now be returned as an array of `DriverIds`. |\n| READ | `stop.allowedDriverIdentifiers` | `stop.allowedDrivers` | Drivers will now be returned as an array of `DriverIds`. |\n| READ | `stop.etaNullReason` | `stop.eta.status` | `eta` now has a status property with the same information. |\n| READ | `stop.timeAtStopInfoNullReason` | `stop.timeAtStopInfo.status` | `timeAtStopInfo` now has a status property with the same information. |\n| READ/WRITE | `stop.circuitClientId` | `stop.clientId` | When creating or reading stops, `circuitClientId` will now be `clientId` |\n| READ | `stop.deliveryInfo.arrivedAt` | `timeAtStopInfo.value.arrivedAt` | This property is only available when `timeAtStopInfo.status === 'available'` |\n\nChanges:\n\n1. READ: `stop.eta` is now an object containing both the eta value, and additional metadata about the value.\n2. READ: `stop.timeAtStopInfo` structure has changed so that the original properties are now under `timeAtStopInfo.value.*`,\n and an additional field `timeAtStopInfo.status` has been added to indicate why the info is not set.\n\n### Plans\n\nChanges:\n\n1. Previously we would allow `Drivers` to be added even if their `Depot` did not match the plan's `Depot`.\n This is no longer allowed. Non-matching `Drivers` must now have their `Depot` changed to match the target `Plan`,\n or vice versa.\n2. `Driver` objects are no longer returned as part of `Plan` endpoint responses. Instead, `DriverIds` are returned and\n the associated drivers must be fetched separately (if needed).\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/v1`\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/v1/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/v1/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/v1/`serializedId`\" -u yourApiKey:\n```\n\nFor the example above this would be:\n\n```bash\ncurl \"https://api.spoke.com/public/v1/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/v1/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/v1/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/v1/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 10 requests per _minute_. However, these endpoints can handle the\n import of up to 1,000 stops per minute. The Creation, Update, and Deletion\n endpoints for these models still maintain a rate limit of 5 requests per\n 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 3 requests per _minute_, due to\n 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## Stop Search API\n\nSince V1 of the API, a new [stop search endpoint](/api/v1#tag/Stops/operation/searchStops) is available. This endpoint allows searching across\nall stop documents (including unassigned stops), within your permitted data lifecycle.\n\nThe endpoint features full-text keyword search as well as a filtering DSL for including or excluding documents\nfrom the search.\n\n### Keywords\n\nThe most basic use of search is to simply provide keywords with the `keyword` parameter.\nThis will perform a fuzzy full-text search across all applicable text fields in the stop\ndocuments and return the results sorted by relevance (by default).\n\nFor example:\n\n`?keyword=london`\n\n### Filtering DSL\n\nFiltering is performed with a simple, SQL-inspired language. It allows for precise queries\nusing comparison operators and boolean logic.\n\nFor example (non-url-encoded for clarity):\n\n`?filter=address.placeId != \"ChIJj61dQgK6j4AR4GeTYWZsKWw\" and address.countryCode = \"DE\"`\n\n#### Syntax Overview\n\nA filter expression consists of a field path, a comparison operator, and a value:\n\n`[field] [operator] [value]`\n\nMultiple expressions can be combined using boolean operators:\n\n`[condition1] and ([condition2] or [condition3])`\n\n> **Note on encoding: These expressions should be url-encoded before being passed to the API**:\n\n---\n\n#### Supported Data Types\n\nThe DSL uses strictly typed fields and values. The following table describes the available data types and how to represent them in a filter string.\n\n| Type | Description | Examples |\n| :---------- | :------------------------------------------------------ | :--------------------------------------- |\n| **String** | Text values enclosed in **double quotes**. | `\"active\"`, `\"John Doe\"`, `\"2026-01-01\"` |\n| **Integer** | Whole numbers, positive or negative. | `123`, `-10`, `0` |\n| **Float** | Decimal numbers, positive or negative. | `123.45`, `-33.8688` |\n| **Boolean** | Logical values `true` or `false`. Case-insensitive. | `true`, `FALSE`, `True` |\n| **Null** | Represents an empty or missing value. Case-insensitive. | `null`, `NULL` |\n\n---\n\n#### Comparison Operators\n\nThe following operators are available for comparing fields against values.\n\n| Operator | Name | Description | Supported Types |\n| :------- | :--------------- | :---------------------------------------------------------- | :----------------- |\n| `=` | Equals | Field value exactly matches the provided value. | All types |\n| `!=` | Not Equals | Field value does not match the provided value. | All types |\n| `~=` | Phrase Match | Field value contains the provided string (substring match). | String |\n| `>` | Greater Than | Field value is strictly greater than the provided value. | String, Int, Float |\n| `>=` | Greater or Equal | Field value is greater than or equal to the provided value. | String, Int, Float |\n| `<` | Less Than | Field value is strictly less than the provided value. | String, Int, Float |\n| `<=` | Less or Equal | Field value is less than or equal to the provided value. | String, Int, Float |\n\n> **Note on String Comparisons**: The operators `>`, `>=`, `<`, and `<=` can only be used with ISO-8601 date strings (e.g., `createdAt > \"2026-01-01\"`).\n\n---\n\n#### Boolean Operators\n\nBoolean operators allow you to combine multiple comparison filters into complex queries.\n\n| Operator | Description | Precedence |\n| :------- | :--------------------------------------------- | :--------- |\n| `and` | Returns true if both conditions are met. | 2 (Higher) |\n| `or` | Returns true if at least one condition is met. | 1 (Lower) |\n\n_Operators are case-insensitive (`AND`, `and`, `And` are all valid)._\n\n#### Grouping and Precedence\n\nBy default, `and` has higher precedence than `or`. You can use **parentheses `()`** to group conditions and override this behaviour.\n\n- `a = 1 or b = 2 and c = 3` is evaluated as `a = 1 or (b = 2 and c = 3)`.\n- `(a = 1 or b = 2) and c = 3` forces the `or` condition to be evaluated first.\n\n---\n\n#### Fields and Paths\n\nFields represent the attribute of the resource you are filtering.\n\n- **Nested Fields**: Use dot notation to access nested attributes (e.g., `address.countryCode`).\n\n#### Custom Properties\n\nTeams can create custom properties for stops. These can be used in filters via the\ncustom property's ID (not the name) as a nested field.\n\nFor example:\n\n```\ncustom_property.0234-5678-0abc-def3 = \"value\"\n```\n\nTo know the ID of a custom property, use the [custom properties list endpoint](https://developer.dispatch.spoke.com/api/v1#tag/Team/operation/listCustomStopProperties).\n\n---\n\n#### Data Freshness\n\nNote that data is ingested into the search index more slowly than the realtime API. This means a\nstop may not be immediately available in the search index after it is created. If you need to fetch\na stop immediately, you should always use the stop restful resources e.g. [fetch stop](/api/v1#tag/Stops/operation/getStop)\n\n#### Examples\n\nThe following are examples of valid, parsable filter strings (field names are examples and may not valid for stops):\n\n- **Simple Equality**: `address.countryCode = \"DE\"` - return all stops where the countryCode is exactly \"DE\".\n- **Numeric Comparison**: `address.latitude >= 100` - return all stops where the latitude is greater than or equal to 100.\n- **Substring Search**: `address ~= \"London\"` - return all stops where the address contains \"London\".\n- **Null Check**: `arrivalTime = null` - return all stops where the arrivalTime field is not set.\n- **Boolean Check**: `deliveryInfo.attempted = true` - return all stops where deliveryInfo.attempted is set to true.\n- **Combined Logic**: `address ~= \"London\" and address.countryCode = \"GB\"` - return all stops where the address contains \"London\" and the country code is \"GB\".\n- **Multiple Options**: `address ~= \"London\" or address ~= \"Bristol\" or address ~= \"Manchester\"` - return all stops where the address contains either London, Bristol or Manchester.\n- **Complex Grouping**: `(address ~= \"London\" or address ~= \"Manchester\") and (createdAt >= \"2026-05-01T00:00:00Z\" and createdAt < \"2026-05-02T00:00:00Z\")` - return all stops where the address contains London or Manchester that were created on 2026-05-01.\n- **Date Range**: `createdat >= \"2026-05-01T00:00:00Z\" and createdAt < \"2026-06-01T00:00:00Z\"` - return all stops created in May 2026.\n\nFor code samples see [Searching Stops](/docs/v1/api-examples/search-stops)\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": "v1" }, "components": { "securitySchemes": { "BasicAuth": { "type": "http", "scheme": "basic", "description": "Use the API key as the username and leave the password empty." } }, "schemas": { "customStopPropertySchema": { "type": "object", "properties": { "id": { "type": "string", "description": "The custom stop property id" }, "name": { "type": "string", "description": "The name of the custom stop property" }, "visibleToDrivers": { "type": "boolean", "description": "Whether this custom stop property is visible to drivers." }, "visibleToRecipients": { "type": "boolean", "description": "Whether this property is visible to recipients." } }, "required": [ "id", "name", "visibleToDrivers", "visibleToRecipients" ], "additionalProperties": false, "description": "The definition of a custom stop property." }, "dateSchema": { "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": "A date." }, "depotIdSchema": { "type": "string", "pattern": "^depots\\/[a-zA-Z0-9---_]{1,50}$" }, "depotSchema": { "type": "object", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/depotIdSchema" } ], "description": "The depot id, in the format `depots/`" }, "name": { "type": "string", "description": "The name of the depot." }, "routeOverrides": { "anyOf": [ { "type": "object", "properties": { "startTime": { "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": "Default route start time." }, "startAddress": { "type": "object", "properties": { "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The full address." }, "addressLineOne": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The first line of the address." }, "addressLineTwo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The second line of the address." }, "latitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Latitude coordinate of the depot in decimal degrees." }, "longitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Longitude coordinate of the depot in decimal degrees." }, "placeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A Google PlaceID identifying the location of the depot." }, "countryCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The country code of the address." } }, "required": [ "address", "addressLineOne", "addressLineTwo", "latitude", "longitude", "placeId", "countryCode" ], "description": "The default start address for routes originating from this depot." }, "defaultTimeAtStop": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Estimated time at stop in seconds." }, "endAddress": { "anyOf": [ { "type": "object", "properties": { "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The full address." }, "addressLineOne": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The first line of the address." }, "addressLineTwo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The second line of the address." }, "latitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Latitude coordinate of the depot in decimal degrees." }, "longitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Longitude coordinate of the depot in decimal degrees." }, "placeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A Google PlaceID identifying the location of the depot." }, "countryCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The country code of the address." } }, "required": [ "address", "addressLineOne", "addressLineTwo", "latitude", "longitude", "placeId", "countryCode" ], "description": "The default end address for routes originating from this depot (if empty, assume a round-trip)." }, { "type": "null" } ] }, "endTime": { "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": "Default route end time." }, { "type": "null" } ] }, "maxStops": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Max stops assigned to each driver" }, "roadSide": { "anyOf": [ { "type": "string", "enum": [ "any", "left_only", "right_only" ] }, { "type": "null" } ], "description": "The side of the road drivers should stop at." }, "vehicleType": { "anyOf": [ { "type": "string", "enum": [ "bike", "scooter", "car", "small_truck", "truck", "electric_cargo_bike" ] }, { "type": "null" } ], "description": "Default vehicle type for new routes from this depot." }, "roundTrip": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Return to start address at end of route" } }, "required": [ "startTime", "startAddress" ] }, { "type": "null" } ] } }, "required": [ "id", "name", "routeOverrides" ], "additionalProperties": false, "description": "A depot." }, "driverIdSchema": { "type": "string", "pattern": "^drivers\\/[a-zA-Z0-9---_]{1,50}$" }, "driverSchema": { "type": "object", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/driverIdSchema" } ], "description": "The driver id, in the format `drivers/`" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The name of the driver." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The email of the driver." }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The phone number of the driver." }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The display name of the driver." }, "active": { "type": "boolean", "description": "Whether the driver membership is active or paused. Paused drivers will not be assigned to any routes." }, "depots": { "type": "array", "items": { "$ref": "#/components/schemas/depotIdSchema" }, "description": "Depots associated with the driver." }, "routeOverrides": { "type": "object", "properties": { "startTime": { "anyOf": [ { "$ref": "#/components/schemas/timeOfDaySchema" }, { "type": "null" } ], "description": "Driver's start time." }, "endTime": { "anyOf": [ { "$ref": "#/components/schemas/timeOfDaySchema" }, { "type": "null" } ], "description": "Driver's end time." }, "startAddress": { "anyOf": [ { "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." }, { "type": "null" } ], "description": "Driver's start location." }, "endAddress": { "anyOf": [ { "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." }, { "type": "null" } ], "description": "Driver's end location." }, "maxStops": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Maximum number of Stops the Driver can take in a route." }, "drivingSpeed": { "type": "string", "enum": [ "slower", "average", "faster" ], "description": "The relative driving speed of the driver compared to others." }, "deliverySpeed": { "type": "string", "enum": [ "slower", "average", "faster" ], "description": "The relative delivery speed of the driver compared to others." }, "vehicleType": { "anyOf": [ { "type": "string", "enum": [ "bike", "scooter", "car", "small_truck", "truck", "electric_cargo_bike" ] }, { "type": "null" } ], "description": "The vehicle type the driver will be using for deliveries." } }, "required": [ "startTime", "endTime", "startAddress", "endAddress", "maxStops", "drivingSpeed", "deliverySpeed", "vehicleType" ], "description": "Settings to override default route settings." } }, "required": [ "id", "name", "email", "phone", "displayName", "active", "depots", "routeOverrides" ], "additionalProperties": false, "description": "A driver." }, "memberIdSchema": { "type": "string", "pattern": "^members\\/[a-zA-Z0-9---_]{1,50}$" }, "memberSchema": { "type": "object", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/memberIdSchema" } ], "description": "The member id, in the format `members/`" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The name of the member." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The email of the member." }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The phone number of the member." }, "linkedDriverId": { "anyOf": [ { "$ref": "#/components/schemas/driverIdSchema" }, { "type": "null" } ], "description": "The driver linked to the member (where applicable)." }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The display name of the member." }, "active": { "type": "boolean", "description": "Whether the member membership is active or paused." }, "depots": { "type": "array", "items": { "type": "string", "pattern": "^depots\\/[a-zA-Z0-9---_]{1,50}$" }, "description": "Depots associated with the member." }, "roles": { "$ref": "#/components/schemas/roleSchema" } }, "required": [ "id", "name", "email", "phone", "linkedDriverId", "displayName", "active", "depots", "roles" ], "additionalProperties": false, "description": "A dashboard member." }, "operationIdSchema": { "type": "string", "pattern": "^operations\\/[a-zA-Z0-9---_]{1,50}$" }, "operationSchema": { "type": "object", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/operationIdSchema" } ], "description": "The id of the operation, in the format `operations/`." }, "type": { "type": "string", "enum": [ "plan_optimization" ] }, "done": { "type": "boolean", "description": "Whether the operation is done." }, "metadata": { "type": "object", "properties": { "canceled": { "type": "boolean", "description": "Whether the operation was canceled." }, "startedAt": { "type": "number", "description": "The time the operation started at, in seconds since epoch." }, "finishedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The time the operation finished at, in seconds since epoch." }, "startedBy": { "anyOf": [ { "type": "string", "enum": [ "dispatcher" ] }, { "type": "string", "enum": [ "api" ] }, { "type": "string" } ], "description": "The entity that started the operation." }, "targetPlanId": { "allOf": [ { "$ref": "#/components/schemas/planIdSchema" } ], "description": "The id of the plan, in the format `plans/`." } }, "required": [ "canceled", "startedAt", "finishedAt", "startedBy", "targetPlanId" ], "description": "Metadata related to a plan optimization operation." }, "result": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "numOptimizedStops": { "type": "number", "description": "The number of stops that were considered for optimization." }, "skippedStops": { "type": "array", "items": { "type": "object", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/stopIdSchema" } ], "description": "The id of the stop, in the format `plans//stops/`." }, "reason": { "anyOf": [ { "type": "string", "enum": [ "impossible_time_window" ] }, { "type": "string", "enum": [ "impossible_navigation" ] }, { "type": "string", "enum": [ "impossible_number_of_stops" ] }, { "type": "string", "enum": [ "impossible_order_of_stops" ] }, { "type": "string" } ], "description": "The reason the stop was skipped." } }, "required": [ "id", "reason" ] }, "description": "The stops that were skipped, if any." } }, "required": [ "numOptimizedStops", "skippedStops" ] }, { "type": "object", "properties": { "code": { "type": "string", "description": "A code that identifies the error" }, "message": { "type": "string", "description": "A human-readable message that describes the error. This message is not intended to be parsed by machines." } }, "required": [ "code", "message" ] } ] }, { "type": "null" } ], "description": "The result of the plan optimization operation, or an error." } }, "required": [ "id", "type", "done", "metadata", "result" ] }, "planIdSchema": { "type": "string", "pattern": "^plans\\/[a-zA-Z0-9---_]{1,50}$" }, "planSchema": { "type": "object", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/planIdSchema" } ], "description": "The unique identifier of the plan." }, "title": { "type": "string", "description": "The title of the plan." }, "starts": { "$ref": "#/components/schemas/dateSchema" }, "depot": { "anyOf": [ { "$ref": "#/components/schemas/depotIdSchema" }, { "type": "null" } ], "description": "The depot ID of the plan, in the format depots/" }, "distributed": { "type": "boolean", "description": "Whether the plan has been distributed." }, "writable": { "type": "boolean", "description": "Whether the plan is writable using the normal Plan APIs. If this is false, you will need to use the [Live Plan APIs](/api/v1#tag/Live-Plans) to edit the plan. Any plan created before 2023-04-01 is not writable." }, "optimization": { "anyOf": [ { "type": "string", "enum": [ "creating", "editing", "preview", "optimized", "optimizing" ] }, { "type": "null" } ], "description": "The optimization state of the plan." }, "drivers": { "type": "array", "items": { "$ref": "#/components/schemas/driverIdSchema" }, "description": "The driver IDs of the plan, in the format drivers/." }, "routes": { "type": "array", "items": { "$ref": "#/components/schemas/routeIdSchema" }, "description": "The route IDs of the plan, in the format routes/." }, "routeOverrides": { "anyOf": [ { "type": "object", "properties": { "startTime": { "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": "Plan's start time." }, "endTime": { "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": "Plan's end time." }, "startAddress": { "anyOf": [ { "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." }, { "type": "null" } ], "description": "Plan's start location." }, "endAddress": { "anyOf": [ { "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." }, { "type": "null" } ], "description": "Plan's end location." }, "maxStops": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Maximum number of Stops per route." }, "drivingSpeed": { "anyOf": [ { "type": "string", "enum": [ "slower", "average", "faster" ] }, { "type": "null" } ], "description": "The relative driving speed compared to others." }, "deliverySpeed": { "anyOf": [ { "type": "string", "enum": [ "slower", "average", "faster" ] }, { "type": "null" } ], "description": "The relative delivery speed compared to others." }, "vehicleType": { "anyOf": [ { "type": "string", "enum": [ "bike", "scooter", "car", "small_truck", "truck", "electric_cargo_bike" ] }, { "type": "null" } ], "description": "The vehicle type used for deliveries." }, "optimizationSettings": { "type": "object", "properties": { "objective": { "type": "string", "enum": [ "minimize_drivers", "distribute_services" ], "description": "The primary optimization objective." }, "subObjective": { "anyOf": [ { "type": "string", "enum": [ "equalize_workload", "equalize_time", "maximize_efficiency" ], "description": "The secondary optimization objective." }, { "type": "null" } ] } }, "required": [ "objective" ], "additionalProperties": false, "description": "Optimization settings for the plan." } }, "required": [ "startTime", "endTime", "startAddress", "endAddress", "maxStops", "drivingSpeed", "deliverySpeed", "vehicleType", "optimizationSettings" ], "additionalProperties": false, "description": "Settings for this plan to override default route configurations." }, { "type": "null" } ], "description": "Settings for this plan to override default route configurations." } }, "required": [ "id", "title", "starts", "depot", "distributed", "writable", "optimization", "drivers", "routes", "routeOverrides" ], "additionalProperties": false, "description": "A plan." }, "roleSchema": { "type": "array", "items": { "type": "string", "enum": [ "owner", "admin", "depot-manager", "dispatcher", "read-only", "driver" ] }, "description": "The role(s) given to the member." }, "routeIdSchema": { "type": "string", "pattern": "^routes\\/[a-zA-Z0-9---_]{1,50}$" }, "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": { "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." }, "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." }, "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": 1, "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" } }, "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" ], "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." }, "unassignedStopIdSchema": { "type": "string", "pattern": "^unassignedStops\\/[a-zA-Z0-9---_]{1,50}$" }, "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." }, "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." }, "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": 1, "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." } } }, "paths": { "/plans": { "post": { "operationId": "createPlan", "summary": "Create a new plan", "tags": [ "Plans" ], "requestBody": { "content": { "application/json": { "schema": { "description": "The request body for creating a plan.", "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "starts": { "description": "The date the plan starts. Does not accept dates that are too far in the future or past.", "type": "object", "properties": { "day": { "description": "The day of the date.", "type": "integer", "minimum": 1, "maximum": 31 }, "month": { "description": "The month of the date.", "type": "integer", "minimum": 1, "maximum": 12 }, "year": { "description": "The year of the date.", "type": "integer", "minimum": 2000, "maximum": 2100 } }, "required": [ "day", "month", "year" ], "additionalProperties": false }, "drivers": { "default": [], "description": "The drivers IDs of the plan, in the format `drivers/`, duplicates will be ignored", "maxItems": 50, "type": "array", "items": { "description": "The driver id, in the format `drivers/`", "type": "string", "pattern": "^drivers\\/[a-zA-Z0-9---_]{1,50}$" } }, "depot": { "description": "The depot id, in the format `depots/`. If not provided, the team's Main Depot will be used.", "anyOf": [ { "type": "string", "pattern": "^depots\\/[a-zA-Z0-9---_]{1,50}$" }, { "type": "null" } ] }, "routeOverrides": { "description": "Overrides for the plan route behavior.", "anyOf": [ { "type": "object", "properties": { "startAddress": { "description": "Address of a start location for every route in this plan. If the latitude and longitude fields are set they will override any of the others. The addressName field is not used for geocoding and is only for display purposes.", "anyOf": [ { "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 }, { "type": "null" } ] }, "endAddress": { "description": "Address of an end location for every route in this plan. If the latitude and longitude fields are set they will override any of the others. The addressName field is not used for geocoding and is only for display purposes.", "anyOf": [ { "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 }, { "type": "null" } ] }, "startTime": { "description": "The start time for the driver's work day.", "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" } ] }, "endTime": { "description": "The end time for the driver's work day.", "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" } ] }, "maxStops": { "description": "The maximum number of stops that can be allocated per route. Note that this setting will be ignored when vehicle capacity or pickups are being used.", "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "drivingSpeed": { "anyOf": [ { "description": "How fast drivers drive compared to the Team's average", "type": "string", "enum": [ "slower", "average", "faster" ] }, { "type": "null" } ] }, "deliverySpeed": { "description": "How fast drivers deliver compared to the Team's average", "anyOf": [ { "type": "string", "enum": [ "slower", "average", "faster" ] }, { "type": "null" } ] }, "vehicleType": { "description": "The type of vehicle used for routes in this plan", "anyOf": [ { "type": "string", "enum": [ "bike", "scooter", "car", "small_truck", "truck", "electric_cargo_bike" ] }, { "type": "null" } ] }, "optimizationSettings": { "description": "Optimization settings for the plan.", "anyOf": [ { "description": "Configures the optimization settings for routes.", "type": "object", "properties": { "objective": { "description": "The primary optimization objective.", "anyOf": [ { "type": "string", "enum": [ "distribute_services" ] }, { "type": "null" } ] }, "subObjective": { "description": "The secondary optimization objective.", "anyOf": [ { "type": "string", "enum": [ "equalize_workload", "equalize_time", "maximize_efficiency" ] }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "title", "starts" ], "additionalProperties": false } } }, "required": true, "description": "The request body for creating a plan." }, "responses": { "200": { "description": "The created plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/planSchema", "description": "The created plan" } } } }, "400": { "description": "The request is invalid, or a driver is not active.", "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": "Failed to validate the request" }, { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Driver is not active" ] }, "code": { "type": "string", "enum": [ "driver_not_active" ] }, "param": { "type": "string", "description": "The parameter that caused the error." } }, "required": [ "message", "code" ], "description": "The driver is not active", "title": "Driver is not active" } ], "description": "The request is invalid, or a driver is not active." } } } }, "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 depot or driver could not be found.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Depot not found" ] } }, "required": [ "message" ], "description": "The provided depot id does not exist", "title": "Depot not found" }, { "type": "object", "properties": { "message": { "anyOf": [ { "type": "string", "enum": [ "Driver not found" ] }, { "type": "string" } ] } }, "required": [ "message" ], "description": "The provided driver id does not exist", "title": "Driver not found" } ], "description": "The depot or driver could not be found." } } } }, "409": { "description": "Depot not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Depot not found" ] }, "code": { "type": "string", "enum": [ "depot_not_found" ] } }, "required": [ "message", "code" ], "description": "Depot not found", "title": "Depot 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" } } } } } }, "get": { "operationId": "listPlans", "summary": "List plans", "tags": [ "Plans" ], "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": 20 }, "in": "query", "name": "maxPageSize", "required": false, "description": "The max page size." }, { "schema": { "type": "object", "properties": { "title": { "description": "Filter by title, exact match", "type": "string", "minLength": 1, "maxLength": 255 }, "startsGte": { "description": "Search for plans that start after this date, inclusive. The date must be in the format YYYY-MM-DD.", "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" }, "startsLte": { "description": "Search for plans that start before this date,inclusive. The date must be in the format YYYY-MM-DD.", "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" } }, "additionalProperties": false }, "in": "query", "name": "filter", "required": false, "description": "The filter to apply to the list of plans. The filter params are passed like this: `?filter[title]=foo` or like this: `?filter.title=foo`" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "plans": { "type": "array", "items": { "$ref": "#/components/schemas/planSchema" }, "description": "The plans list." }, "nextPageToken": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The next page token." } }, "required": [ "plans", "nextPageToken" ], "definitions": { "planSchema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^plans\\/[a-zA-Z0-9---_]{1,50}$", "description": "The unique identifier of the plan." }, "title": { "type": "string", "description": "The title of the plan." }, "starts": { "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": "A date." }, "depot": { "anyOf": [ { "type": "string", "pattern": "^depots\\/[a-zA-Z0-9---_]{1,50}$" }, { "type": "null" } ], "description": "The depot ID of the plan, in the format depots/" }, "distributed": { "type": "boolean", "description": "Whether the plan has been distributed." }, "writable": { "type": "boolean", "description": "Whether the plan is writable using the normal Plan APIs. If this is false, you will need to use the [Live Plan APIs](/api/v1#tag/Live-Plans) to edit the plan. Any plan created before 2023-04-01 is not writable." }, "optimization": { "anyOf": [ { "type": "string", "enum": [ "creating", "editing", "preview", "optimized", "optimizing" ] }, { "type": "null" } ], "description": "The optimization state of the plan." }, "drivers": { "type": "array", "items": { "type": "string", "pattern": "^drivers\\/[a-zA-Z0-9---_]{1,50}$" }, "description": "The driver IDs of the plan, in the format drivers/." }, "routes": { "type": "array", "items": { "type": "string", "pattern": "^routes\\/[a-zA-Z0-9---_]{1,50}$" }, "description": "The route IDs of the plan, in the format routes/." }, "routeOverrides": { "anyOf": [ { "type": "object", "properties": { "startTime": { "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": "Plan's start time." }, "endTime": { "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": "Plan's end time." }, "startAddress": { "anyOf": [ { "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." }, { "type": "null" } ], "description": "Plan's start location." }, "endAddress": { "anyOf": [ { "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." }, { "type": "null" } ], "description": "Plan's end location." }, "maxStops": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Maximum number of Stops per route." }, "drivingSpeed": { "anyOf": [ { "type": "string", "enum": [ "slower", "average", "faster" ] }, { "type": "null" } ], "description": "The relative driving speed compared to others." }, "deliverySpeed": { "anyOf": [ { "type": "string", "enum": [ "slower", "average", "faster" ] }, { "type": "null" } ], "description": "The relative delivery speed compared to others." }, "vehicleType": { "anyOf": [ { "type": "string", "enum": [ "bike", "scooter", "car", "small_truck", "truck", "electric_cargo_bike" ] }, { "type": "null" } ], "description": "The vehicle type used for deliveries." }, "optimizationSettings": { "type": "object", "properties": { "objective": { "type": "string", "enum": [ "minimize_drivers", "distribute_services" ], "description": "The primary optimization objective." }, "subObjective": { "anyOf": [ { "type": "string", "enum": [ "equalize_workload", "equalize_time", "maximize_efficiency" ], "description": "The secondary optimization objective." }, { "type": "null" } ] } }, "required": [ "objective" ], "additionalProperties": false, "description": "Optimization settings for the plan." } }, "required": [ "startTime", "endTime", "startAddress", "endAddress", "maxStops", "drivingSpeed", "deliverySpeed", "vehicleType", "optimizationSettings" ], "additionalProperties": false, "description": "Settings for this plan to override default route configurations." }, { "type": "null" } ], "description": "Settings for this plan to override default route configurations." } }, "required": [ "id", "title", "starts", "depot", "distributed", "writable", "optimization", "drivers", "routes", "routeOverrides" ], "additionalProperties": false, "description": "A plan." } }, "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" } } } }, "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}": { "patch": { "operationId": "updatePlan", "summary": "Update an existing plan", "tags": [ "Plans" ], "description": "Update an existing plan. If the plan `writable` property is false, prefer using the [Live Plans API](#tag/Live-Plans).", "requestBody": { "content": { "application/json": { "schema": { "description": "The request body for updating a plan. All the values present in the request will update the plan value, if you wish to update only certain fields, only set them and do not set the others. Any fields not set will not be updated.\n\n**Important:** Notice that the `drivers` Array will be completely replaced. If a single driver is provided in the request, the plan will have all other previous drivers discarded.", "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "starts": { "description": "The date the plan starts. Does not accept dates that are too far in the future or past.", "type": "object", "properties": { "day": { "description": "The day of the date.", "type": "integer", "minimum": 1, "maximum": 31 }, "month": { "description": "The month of the date.", "type": "integer", "minimum": 1, "maximum": 12 }, "year": { "description": "The year of the date.", "type": "integer", "minimum": 2000, "maximum": 2100 } }, "required": [ "day", "month", "year" ], "additionalProperties": false }, "drivers": { "description": "The drivers IDs of the plan, in the format `drivers/`, duplicates will be ignored", "maxItems": 50, "type": "array", "items": { "description": "The driver id, in the format `drivers/`", "type": "string", "pattern": "^drivers\\/[a-zA-Z0-9---_]{1,50}$" } }, "depot": { "description": "The depot id, in the format `depots/`. If not provided, the team's Main Depot will be used.", "anyOf": [ { "type": "string", "pattern": "^depots\\/[a-zA-Z0-9---_]{1,50}$" }, { "type": "null" } ] }, "routeOverrides": { "description": "Overrides for the plan route behavior.", "anyOf": [ { "type": "object", "properties": { "startAddress": { "description": "Address of a start location for every route in this plan. If the latitude and longitude fields are set they will override any of the others. The addressName field is not used for geocoding and is only for display purposes.", "anyOf": [ { "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 }, { "type": "null" } ] }, "endAddress": { "description": "Address of an end location for every route in this plan. If the latitude and longitude fields are set they will override any of the others. The addressName field is not used for geocoding and is only for display purposes.", "anyOf": [ { "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 }, { "type": "null" } ] }, "startTime": { "description": "The start time for the driver's work day.", "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" } ] }, "endTime": { "description": "The end time for the driver's work day.", "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" } ] }, "maxStops": { "description": "The maximum number of stops that can be allocated per route. Note that this setting will be ignored when vehicle capacity or pickups are being used.", "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "drivingSpeed": { "anyOf": [ { "description": "How fast drivers drive compared to the Team's average", "type": "string", "enum": [ "slower", "average", "faster" ] }, { "type": "null" } ] }, "deliverySpeed": { "description": "How fast drivers deliver compared to the Team's average", "anyOf": [ { "type": "string", "enum": [ "slower", "average", "faster" ] }, { "type": "null" } ] }, "vehicleType": { "description": "The type of vehicle used for routes in this plan", "anyOf": [ { "type": "string", "enum": [ "bike", "scooter", "car", "small_truck", "truck", "electric_cargo_bike" ] }, { "type": "null" } ] }, "optimizationSettings": { "description": "Optimization settings for the plan.", "anyOf": [ { "description": "Configures the optimization settings for routes.", "type": "object", "properties": { "objective": { "description": "The primary optimization objective.", "anyOf": [ { "type": "string", "enum": [ "distribute_services" ] }, { "type": "null" } ] }, "subObjective": { "description": "The secondary optimization objective.", "anyOf": [ { "type": "string", "enum": [ "equalize_workload", "equalize_time", "maximize_efficiency" ] }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] } }, "additionalProperties": false } } }, "description": "The request body for updating a plan. All the values present in the request will update the plan value, if you wish to update only certain fields, only set them and do not set the others. Any fields not set will not be updated.\n\n**Important:** Notice that the `drivers` Array will be completely replaced. If a single driver is provided in the request, the plan will have all other previous drivers discarded." }, "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 updated plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/planSchema", "description": "The updated plan" } } } }, "400": { "description": "The request is invalid, or a driver is not active.", "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": "Failed to validate the request" }, { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Driver is not active" ] }, "code": { "type": "string", "enum": [ "driver_not_active" ] }, "param": { "type": "string", "description": "The parameter that caused the error." } }, "required": [ "message", "code" ], "description": "The driver is not active", "title": "Driver is not active" } ], "description": "The request is invalid, or a driver is not active." } } } }, "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 plan, depot, or driver could not be found.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Plan not found" ] } }, "required": [ "message" ], "description": "The provided plan id does not exist", "title": "Plan not found" }, { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Depot not found" ] } }, "required": [ "message" ], "description": "The provided depot id does not exist", "title": "Depot not found" }, { "type": "object", "properties": { "message": { "anyOf": [ { "type": "string", "enum": [ "Driver not found" ] }, { "type": "string" } ] } }, "required": [ "message" ], "description": "The provided driver id does not exist", "title": "Driver not found" } ], "description": "The plan, depot, or driver could not be 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" } } } }, "412": { "description": "Drivers and plans must have the same depot configured", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Driver does not share depot with plan" ] }, "param": { "type": "string", "description": "The parameter that caused the error." } }, "required": [ "message" ], "description": "Drivers and plans must have the same depot configured", "title": "Plan and driver do not share a depot" } } } }, "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": "getPlan", "summary": "Retrieve a plan", "tags": [ "Plans" ], "description": "Retrieve a plan", "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 requested plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/planSchema", "description": "The requested plan" } } } }, "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": "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" } } } } } }, "delete": { "operationId": "deletePlan", "summary": "Delete a plan", "tags": [ "Plans" ], "description": "Delete a plan and related routes. This action cannot be undone and will delete all the releated routes as well, even if the plan is not in a writable state. As this action is not atomic, it is possible that only partial deletion occurs if the endpoint errors out with a 500. In that case it is recommended to retry the request.", "parameters": [ { "schema": { "type": "string", "pattern": "^[a-zA-Z0-9---_]{1,50}$" }, "in": "path", "name": "planId", "required": true, "description": "The plan id" } ], "responses": { "204": { "description": "Plan 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": "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}:optimize": { "post": { "operationId": "optimizePlan", "summary": "Optimize a plan", "tags": [ "Plans" ], "description": "Optimize a plan. Returns the created operation, which can be polled for the result. Use the returned `id` with the [operations](#tag/Operations) endpoints to poll for the result.", "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 plan_optimization operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/operationSchema", "description": "The created plan_optimization operation." } } } }, "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": "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" } } } }, "409": { "description": "The plan is not writable, an optimization is already in progress, there are no drivers, or there is a problem with the depot.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Plan already optimized" ] }, "code": { "type": "string", "enum": [ "plan_already_optimized" ] } }, "required": [ "message", "code" ], "title": "Plan already optimized" }, { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Plan optimization in progress" ] }, "code": { "type": "string", "enum": [ "plan_optimization_in_progress" ] } }, "required": [ "message", "code" ], "description": "The plan's optimization is in progress.", "title": "Plan optimization in progress" }, { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Plan has no drivers. Either the plan's depot has no drivers, if the optimization is for minimizing drivers, or the plan has no assigned drivers." ] }, "code": { "type": "string", "enum": [ "no_drivers_available" ] } }, "required": [ "message", "code" ], "description": "The plan has no available drivers.", "title": "Plan has no drivers" }, { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Please set an end time or max stops per driver for the plan's depot when optimizing to minimize drivers." ] }, "code": { "type": "string", "enum": [ "no_end_time_and_max_stops_per_driver" ] } }, "required": [ "message", "code" ], "description": "The plan's depot has no end time and max stops per driver.", "title": "Plan's depot has no end time and max stops per driver" }, { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Depot not found" ] }, "code": { "type": "string", "enum": [ "depot_not_found" ] } }, "required": [ "message", "code" ], "description": "Depot not found", "title": "Depot not found", "x-response-description": "Depot not found" }, { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Please set a start location for the plan's depot." ] }, "code": { "type": "string", "enum": [ "depot_missing_start_address" ] } }, "required": [ "message", "code" ], "description": "Depot not found", "title": "Plan's depot missing start address" } ], "description": "The plan is not writable, an optimization is already in progress, there are no drivers, or there is a problem with the depot." } } } }, "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}:distribute": { "post": { "operationId": "distributePlan", "summary": "Distribute a plan", "tags": [ "Plans" ], "description": "Distribute a plan to its drivers. This will send then their routes.", "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 distributed plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/planSchema", "description": "The distributed plan" } } } }, "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": "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" } } } }, "409": { "description": "The plan is not yet optimized, is optimizing, was already distributed or was modified whilst processing request.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Plan already distributed" ] }, "code": { "type": "string", "enum": [ "plan_already_distributed" ] } }, "required": [ "message", "code" ], "description": "The plan is already distributed.", "title": "Plan already distributed" }, { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Plan not optimized" ] }, "code": { "type": "string", "enum": [ "plan_not_optimized" ] } }, "required": [ "message", "code" ], "description": "The plan is not optimized.", "title": "Plan not optimized" }, { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Plan optimization in progress" ] }, "code": { "type": "string", "enum": [ "plan_optimization_in_progress" ] } }, "required": [ "message", "code" ], "description": "The plan's optimization is in progress.", "title": "Plan optimization in progress" }, { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Plan was modified by a concurrent request. Please retry your request." ] }, "code": { "type": "string", "enum": [ "plan_concurrent_modification" ] } }, "required": [ "message", "code" ], "description": "Plan modified whilst processing request", "title": "Plan modified whilst processing request" } ], "description": "The plan is not yet optimized, is optimizing, was already distributed or was modified whilst processing request." } } } }, "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}:reoptimize": { "post": { "operationId": "reoptimizePlan", "summary": "Re-optimize a plan", "tags": [ "Live Plans" ], "description": "Re-optimize a plan. This endpoint should be used only after updating a live plan. Returns the created operation, which can be polled for the result. Use the returned `id` with the [operations](#tag/Operations) endpoints to poll for the result.", "requestBody": { "content": { "application/json": { "schema": { "description": "The request body for reoptimize a plan.", "type": "object", "properties": { "optimizationType": { "description": "The type of optimization to use", "default": "reorder_changed_stops", "type": "string", "enum": [ "reorder_changed_stops", "reorder_all_stops", "redistribute_stops_between_drivers" ] } }, "additionalProperties": false } } }, "description": "The request body for reoptimize a plan." }, "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 plan_optimization operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/operationSchema", "description": "The created plan_optimization operation." } } } }, "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": "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" } } } }, "409": { "description": "The plan is not being edited, an optimization is already in progress, there are no drivers, or there is a problem with the depot.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Plan already optimized" ] }, "code": { "type": "string", "enum": [ "plan_already_optimized" ] } }, "required": [ "message", "code" ], "title": "Plan already optimized" }, { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Only `reorder_changed_stops` optimization type is supported when the plan is already distributed." ] }, "code": { "type": "string", "enum": [ "plan_optimization_not_supported" ] } }, "required": [ "message", "code" ], "description": "Plan optimization type is not supported.", "title": "Plan optimization type is not supported" }, { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Plan optimization in progress" ] }, "code": { "type": "string", "enum": [ "plan_optimization_in_progress" ] } }, "required": [ "message", "code" ], "description": "The plan's optimization is in progress.", "title": "Plan optimization in progress" }, { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Plan has no drivers. Either the plan's depot has no drivers, if the optimization is for minimizing drivers, or the plan has no assigned drivers." ] }, "code": { "type": "string", "enum": [ "no_drivers_available" ] } }, "required": [ "message", "code" ], "description": "The plan has no available drivers.", "title": "Plan has no drivers" }, { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Please set an end time or max stops per driver for the plan's depot when optimizing to minimize drivers." ] }, "code": { "type": "string", "enum": [ "no_end_time_and_max_stops_per_driver" ] } }, "required": [ "message", "code" ], "description": "The plan's depot has no end time and max stops per driver.", "title": "Plan's depot has no end time and max stops per driver" }, { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Depot not found" ] }, "code": { "type": "string", "enum": [ "depot_not_found" ] } }, "required": [ "message", "code" ], "description": "Depot not found", "title": "Depot not found", "x-response-description": "Depot not found" }, { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Please set a start location for the plan's depot." ] }, "code": { "type": "string", "enum": [ "depot_missing_start_address" ] } }, "required": [ "message", "code" ], "description": "Depot not found", "title": "Plan's depot missing start address" } ], "description": "The plan is not being edited, an optimization is already in progress, there are no drivers, or there is a problem with the depot." } } } }, "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}:redistribute": { "post": { "operationId": "redistributePlan", "summary": "Re-distribute a plan", "tags": [ "Live Plans" ], "description": "Re-distribute a plan to its drivers. This endpoint should be used only after updating a live plan. This will apply the re-optimization changes and send the drivers their routes.", "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 distributed plan", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/planSchema", "description": "The distributed plan" } } } }, "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": "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" } } } }, "409": { "description": "The plan is not yet optimized, is optimizing, was already distributed or was modified whilst processing request.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Plan already distributed" ] }, "code": { "type": "string", "enum": [ "plan_already_distributed" ] } }, "required": [ "message", "code" ], "description": "The plan is already distributed.", "title": "Plan already distributed" }, { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Plan not optimized" ] }, "code": { "type": "string", "enum": [ "plan_not_optimized" ] } }, "required": [ "message", "code" ], "description": "The plan is not optimized.", "title": "Plan not optimized" }, { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Plan optimization in progress" ] }, "code": { "type": "string", "enum": [ "plan_optimization_in_progress" ] } }, "required": [ "message", "code" ], "description": "The plan's optimization is in progress.", "title": "Plan optimization in progress" }, { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Plan was modified by a concurrent request. Please retry your request." ] }, "code": { "type": "string", "enum": [ "plan_concurrent_modification" ] } }, "required": [ "message", "code" ], "description": "Plan modified whilst processing request", "title": "Plan modified whilst processing request" } ], "description": "The plan is not yet optimized, is optimizing, was already distributed or was modified whilst processing request." } } } }, "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}:save": { "post": { "operationId": "savePlan", "summary": "Save the plan changes", "tags": [ "Live Plans" ], "description": "Save the plan changes after re-optimization without distributing it. This endpoint is optional since re-distribute already saves the changes.", "parameters": [ { "schema": { "type": "string", "pattern": "^[a-zA-Z0-9---_]{1,50}$" }, "in": "path", "name": "planId", "required": true, "description": "The plan id" } ], "responses": { "204": { "description": "Plan saved 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": "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" } } } }, "409": { "description": "The plan is not yet optimized, an optimization is in progress or it was modified whilst processing request.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Plan not optimized" ] }, "code": { "type": "string", "enum": [ "plan_not_optimized" ] } }, "required": [ "message", "code" ], "description": "The plan is not optimized.", "title": "Plan not optimized" }, { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Plan optimization in progress" ] }, "code": { "type": "string", "enum": [ "plan_optimization_in_progress" ] } }, "required": [ "message", "code" ], "description": "The plan's optimization is in progress.", "title": "Plan optimization in progress" }, { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Plan was modified by a concurrent request. Please retry your request." ] }, "code": { "type": "string", "enum": [ "plan_concurrent_modification" ] } }, "required": [ "message", "code" ], "description": "Plan modified whilst processing request", "title": "Plan modified whilst processing request" } ], "description": "The plan is not yet optimized, an optimization is in progress or it was modified whilst processing request." } } } }, "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": { "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": { "description": "The request body for creating a stop. The only required field is address, you need to provide at least one of the fields in it. The latitude and longitude fields will override any of the other fields if they are set(and they need to be both set if any of them are). The more fields you provide the more accurate the geocoding will be.", "type": "object", "properties": { "address": { "type": "object", "properties": { "addressName": { "description": "The name of the address. This will not be used for geocoding, and is only for the final address display purposes.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "addressLineOne": { "description": "The first line of the address.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "addressLineTwo": { "description": "The second line of the address.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "city": { "description": "The city of the address.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "state": { "description": "The state of the address.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "zip": { "description": "The zip code of the address.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "country": { "description": "The country of the address.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "latitude": { "description": "The latitude of the address in decimal degrees.", "anyOf": [ { "type": "number", "minimum": -90, "maximum": 90 }, { "type": "null" } ] }, "longitude": { "description": "The longitude of the address in decimal degrees.", "anyOf": [ { "type": "number", "minimum": -180, "maximum": 180 }, { "type": "null" } ] } }, "additionalProperties": false }, "timing": { "anyOf": [ { "description": "Timing information for this stop", "type": "object", "properties": { "earliestAttemptTime": { "description": "Time of day of the earliest time this stop should happen", "anyOf": [ { "description": "Time of day in hours and minutes. Use a 24 hour clock.", "type": "object", "properties": { "hour": { "description": "Hour of the day", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "minute": { "description": "Minute of the hour", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "hour", "minute" ], "additionalProperties": false }, { "type": "null" } ] }, "latestAttemptTime": { "description": "Time of day of the latest time this stop should happen", "anyOf": [ { "description": "Time of day in hours and minutes. Use a 24 hour clock.", "type": "object", "properties": { "hour": { "description": "Hour of the day", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "minute": { "description": "Minute of the hour", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "hour", "minute" ], "additionalProperties": false }, { "type": "null" } ] }, "estimatedAttemptDuration": { "description": "Duration in seconds of the activity in this stop, only set if you want to override the default. This can be set up to 8 hours.", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "recipient": { "anyOf": [ { "description": "Recipient information for this stop", "type": "object", "properties": { "externalId": { "description": "External ID of the recipient, as defined by the API user", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "email": { "description": "Email of the recipient", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "phone": { "description": "Phone number of the recipient", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "name": { "description": "Name of the recipient", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "orderInfo": { "anyOf": [ { "description": "Order information for this stop", "type": "object", "properties": { "products": { "description": "Products in this stop", "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "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", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "currency": { "description": "Currency of the payment. Defaults to the team's currency.", "anyOf": [ { "type": "string", "enum": [ "AED", "ARS", "AUD", "BRL", "CAD", "CHF", "CLP", "CNY", "COP", "DKK", "EGP", "EUR", "GBP", "HKD", "HUF", "ILS", "INR", "JPY", "KRW", "MYR", "MXN", "NOK", "NZD", "PEN", "RON", "RUB", "SAR", "SEK", "SGD", "TRY", "USD", "UYU", "ZAR" ] }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "proofOfAttemptRequirements": { "anyOf": [ { "description": "Proof of attempt requirement settings for this stop", "type": "object", "properties": { "enabled": { "description": "Whether proof of attempt is required for this stop", "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "allowedDrivers": { "description": "Driver IDs that are allowed to be assigned to this stop. These drivers must be configured as part of the plan to be valid.", "anyOf": [ { "maxItems": 100, "type": "array", "items": { "type": "string", "pattern": "^drivers\\/[a-zA-Z0-9---_]{1,50}$" } }, { "type": "null" } ] }, "activity": { "description": "Activity type", "default": "delivery", "anyOf": [ { "type": "string", "enum": [ "delivery", "pickup" ] }, { "type": "null" } ] }, "optimizationOrder": { "description": "The preferred order of this stop in the optimized route. If not provided or `\"default\"`, the stop will be placed in the optimal order, decided by the optimization algorithm. Otherwise it will be placed either `\"first\"` or `\"last\"`.", "anyOf": [ { "type": "string", "enum": [ "first", "last", "default" ] }, { "type": "null" } ] }, "packageCount": { "description": "Number of packages in the stop", "anyOf": [ { "type": "number", "minimum": 1, "maximum": 10000 }, { "type": "null" } ] }, "weight": { "description": "Weight information for this stop.", "anyOf": [ { "type": "object", "properties": { "amount": { "description": "The weight amount for this stop.", "type": "number", "minimum": 0, "maximum": 999999, "multipleOf": 0.01 }, "unit": { "description": "The weight unit in which the amount is specified.", "type": "string", "enum": [ "kilogram", "pound", "metric-ton" ] } }, "required": [ "amount", "unit" ] }, { "type": "null" } ] }, "notes": { "description": "Notes for the stop", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] }, "clientId": { "description": "Client ID of the retailer in Spoke Connect", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "barcodes": { "description": "List of barcode IDs associated with this stop", "maxItems": 50, "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, "description": "The request body for creating a stop. The only required field is address, you need to provide at least one of the fields in it. The latitude and longitude fields will override any of the other fields if they are set(and they need to be both set if any of them are). The more fields you provide the more accurate the geocoding will be." }, "parameters": [ { "schema": { "type": "string", "pattern": "^[a-zA-Z0-9---_]{1,50}$" }, "in": "path", "name": "planId", "required": true, "description": "The plan id" } ], "responses": { "200": { "description": "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" } } } }, "412": { "description": "Drivers must be part of the plan to be referenced by stops", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Driver is not linked to plan" ] }, "param": { "type": "string", "description": "The parameter that caused the error." } }, "required": [ "message" ], "description": "Drivers must be part of the plan to be referenced by stops", "title": "Driver is not linked to plan" } } } }, "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": "listPlanStops", "summary": "List plan stops", "tags": [ "Plans" ], "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." }, "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." }, "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." }, "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": 1, "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" } }, "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" ], "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": { "description": "The request body for creating a stop. The only required field is address, you need to provide at least one of the fields in it. The latitude and longitude fields will override any of the other fields if they are set(and they need to be both set if any of them are). The more fields you provide the more accurate the geocoding will be.", "type": "object", "properties": { "address": { "type": "object", "properties": { "addressName": { "description": "The name of the address. This will not be used for geocoding, and is only for the final address display purposes.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "addressLineOne": { "description": "The first line of the address.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "addressLineTwo": { "description": "The second line of the address.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "city": { "description": "The city of the address.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "state": { "description": "The state of the address.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "zip": { "description": "The zip code of the address.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "country": { "description": "The country of the address.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "latitude": { "description": "The latitude of the address in decimal degrees.", "anyOf": [ { "type": "number", "minimum": -90, "maximum": 90 }, { "type": "null" } ] }, "longitude": { "description": "The longitude of the address in decimal degrees.", "anyOf": [ { "type": "number", "minimum": -180, "maximum": 180 }, { "type": "null" } ] } }, "additionalProperties": false }, "timing": { "anyOf": [ { "description": "Timing information for this stop", "type": "object", "properties": { "earliestAttemptTime": { "description": "Time of day of the earliest time this stop should happen", "anyOf": [ { "description": "Time of day in hours and minutes. Use a 24 hour clock.", "type": "object", "properties": { "hour": { "description": "Hour of the day", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "minute": { "description": "Minute of the hour", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "hour", "minute" ], "additionalProperties": false }, { "type": "null" } ] }, "latestAttemptTime": { "description": "Time of day of the latest time this stop should happen", "anyOf": [ { "description": "Time of day in hours and minutes. Use a 24 hour clock.", "type": "object", "properties": { "hour": { "description": "Hour of the day", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "minute": { "description": "Minute of the hour", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "hour", "minute" ], "additionalProperties": false }, { "type": "null" } ] }, "estimatedAttemptDuration": { "description": "Duration in seconds of the activity in this stop, only set if you want to override the default. This can be set up to 8 hours.", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "recipient": { "anyOf": [ { "description": "Recipient information for this stop", "type": "object", "properties": { "externalId": { "description": "External ID of the recipient, as defined by the API user", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "email": { "description": "Email of the recipient", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "phone": { "description": "Phone number of the recipient", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "name": { "description": "Name of the recipient", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "orderInfo": { "anyOf": [ { "description": "Order information for this stop", "type": "object", "properties": { "products": { "description": "Products in this stop", "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "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", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "currency": { "description": "Currency of the payment. Defaults to the team's currency.", "anyOf": [ { "type": "string", "enum": [ "AED", "ARS", "AUD", "BRL", "CAD", "CHF", "CLP", "CNY", "COP", "DKK", "EGP", "EUR", "GBP", "HKD", "HUF", "ILS", "INR", "JPY", "KRW", "MYR", "MXN", "NOK", "NZD", "PEN", "RON", "RUB", "SAR", "SEK", "SGD", "TRY", "USD", "UYU", "ZAR" ] }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "proofOfAttemptRequirements": { "anyOf": [ { "description": "Proof of attempt requirement settings for this stop", "type": "object", "properties": { "enabled": { "description": "Whether proof of attempt is required for this stop", "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "allowedDrivers": { "description": "Driver IDs that are allowed to be assigned to this stop. These drivers must be configured as part of the plan to be valid.", "anyOf": [ { "maxItems": 100, "type": "array", "items": { "type": "string", "pattern": "^drivers\\/[a-zA-Z0-9---_]{1,50}$" } }, { "type": "null" } ] }, "activity": { "description": "Activity type", "default": "delivery", "anyOf": [ { "type": "string", "enum": [ "delivery", "pickup" ] }, { "type": "null" } ] }, "optimizationOrder": { "description": "The preferred order of this stop in the optimized route. If not provided or `\"default\"`, the stop will be placed in the optimal order, decided by the optimization algorithm. Otherwise it will be placed either `\"first\"` or `\"last\"`.", "anyOf": [ { "type": "string", "enum": [ "first", "last", "default" ] }, { "type": "null" } ] }, "packageCount": { "description": "Number of packages in the stop", "anyOf": [ { "type": "number", "minimum": 1, "maximum": 10000 }, { "type": "null" } ] }, "weight": { "description": "Weight information for this stop.", "anyOf": [ { "type": "object", "properties": { "amount": { "description": "The weight amount for this stop.", "type": "number", "minimum": 0, "maximum": 999999, "multipleOf": 0.01 }, "unit": { "description": "The weight unit in which the amount is specified.", "type": "string", "enum": [ "kilogram", "pound", "metric-ton" ] } }, "required": [ "amount", "unit" ] }, { "type": "null" } ] }, "notes": { "description": "Notes for the stop", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] }, "clientId": { "description": "Client ID of the retailer in Spoke Connect", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "barcodes": { "description": "List of barcode IDs associated with this stop", "maxItems": 50, "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" } } } }, "412": { "description": "Drivers must be part of the plan to be referenced by stops", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Driver is not linked to plan" ] }, "param": { "type": "string", "description": "The parameter that caused the error." } }, "required": [ "message" ], "description": "Drivers must be part of the plan to be referenced by stops", "title": "Driver is not linked to plan" } } } }, "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 `clientId`. 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": { "description": "The request body for updating a stop. All the values present in the request will update the stop value, if you wish to update only certain fields, only set them and do not set the others. Any fields not set will not be updated.", "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", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "currency": { "description": "Currency of the payment. Defaults to the team's currency.", "anyOf": [ { "type": "string", "enum": [ "AED", "ARS", "AUD", "BRL", "CAD", "CHF", "CLP", "CNY", "COP", "DKK", "EGP", "EUR", "GBP", "HKD", "HUF", "ILS", "INR", "JPY", "KRW", "MYR", "MXN", "NOK", "NZD", "PEN", "RON", "RUB", "SAR", "SEK", "SGD", "TRY", "USD", "UYU", "ZAR" ] }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "proofOfAttemptRequirements": { "anyOf": [ { "description": "Proof of attempt requirement settings for this stop", "type": "object", "properties": { "enabled": { "description": "Whether proof of attempt is required for this stop", "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "allowedDrivers": { "description": "Driver IDs that are allowed to be assigned to this stop. These drivers must be configured as part of the plan to be valid.", "anyOf": [ { "maxItems": 100, "type": "array", "items": { "type": "string", "pattern": "^drivers\\/[a-zA-Z0-9---_]{1,50}$" } }, { "type": "null" } ] }, "activity": { "description": "Activity type", "default": "delivery", "anyOf": [ { "type": "string", "enum": [ "delivery", "pickup" ] }, { "type": "null" } ] }, "optimizationOrder": { "description": "The preferred order of this stop in the optimized route. If not provided or `\"default\"`, the stop will be placed in the optimal order, decided by the optimization algorithm. Otherwise it will be placed either `\"first\"` or `\"last\"`.", "anyOf": [ { "type": "string", "enum": [ "first", "last", "default" ] }, { "type": "null" } ] }, "packageCount": { "description": "Number of packages in the stop", "anyOf": [ { "type": "number", "minimum": 1, "maximum": 10000 }, { "type": "null" } ] }, "weight": { "description": "Weight information for this stop.", "anyOf": [ { "type": "object", "properties": { "amount": { "description": "The weight amount for this stop.", "type": "number", "minimum": 0, "maximum": 999999, "multipleOf": 0.01 }, "unit": { "description": "The weight unit in which the amount is specified.", "type": "string", "enum": [ "kilogram", "pound", "metric-ton" ] } }, "required": [ "amount", "unit" ] }, { "type": "null" } ] }, "notes": { "description": "Notes for the stop", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] }, "barcodes": { "description": "List of barcode IDs associated with this stop", "maxItems": 50, "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 } } }, "description": "The request body for updating a stop. All the values present in the request will update the stop value, if you wish to update only certain fields, only set them and do not set the others. Any fields not set will not be updated." }, "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" } } } }, "412": { "description": "Drivers must be part of the plan to be referenced by stops", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Driver is not linked to plan" ] }, "param": { "type": "string", "description": "The parameter that caused the error." } }, "required": [ "message" ], "description": "Drivers must be part of the plan to be referenced by stops", "title": "Driver is not linked to plan" } } } }, "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": "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" } } } } } } }, "/plans/{planId}/stops:liveCreate": { "post": { "operationId": "createLiveStop", "summary": "Create a new stop", "tags": [ "Live Stops" ], "description": "Create a new stop with the given data on live plans. When the plan is not writable, this endpoint starts an editing session and the action can be applied through a new optimization, or be discarded. Prefer using the [batch import endpoint](#tag/Stops/operation/importLiveStops) if you want to create multiple stops at once as it is more efficient and will produce better geocoding results.", "requestBody": { "content": { "application/json": { "schema": { "description": "The request body for creating a stop. The only required field is address, you need to provide at least one of the fields in it. The latitude and longitude fields will override any of the other fields if they are set(and they need to be both set if any of them are). The more fields you provide the more accurate the geocoding will be.", "type": "object", "properties": { "address": { "type": "object", "properties": { "addressName": { "description": "The name of the address. This will not be used for geocoding, and is only for the final address display purposes.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "addressLineOne": { "description": "The first line of the address.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "addressLineTwo": { "description": "The second line of the address.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "city": { "description": "The city of the address.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "state": { "description": "The state of the address.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "zip": { "description": "The zip code of the address.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "country": { "description": "The country of the address.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "latitude": { "description": "The latitude of the address in decimal degrees.", "anyOf": [ { "type": "number", "minimum": -90, "maximum": 90 }, { "type": "null" } ] }, "longitude": { "description": "The longitude of the address in decimal degrees.", "anyOf": [ { "type": "number", "minimum": -180, "maximum": 180 }, { "type": "null" } ] } }, "additionalProperties": false }, "timing": { "anyOf": [ { "description": "Timing information for this stop", "type": "object", "properties": { "earliestAttemptTime": { "description": "Time of day of the earliest time this stop should happen", "anyOf": [ { "description": "Time of day in hours and minutes. Use a 24 hour clock.", "type": "object", "properties": { "hour": { "description": "Hour of the day", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "minute": { "description": "Minute of the hour", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "hour", "minute" ], "additionalProperties": false }, { "type": "null" } ] }, "latestAttemptTime": { "description": "Time of day of the latest time this stop should happen", "anyOf": [ { "description": "Time of day in hours and minutes. Use a 24 hour clock.", "type": "object", "properties": { "hour": { "description": "Hour of the day", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "minute": { "description": "Minute of the hour", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "hour", "minute" ], "additionalProperties": false }, { "type": "null" } ] }, "estimatedAttemptDuration": { "description": "Duration in seconds of the activity in this stop, only set if you want to override the default. This can be set up to 8 hours.", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "recipient": { "anyOf": [ { "description": "Recipient information for this stop", "type": "object", "properties": { "externalId": { "description": "External ID of the recipient, as defined by the API user", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "email": { "description": "Email of the recipient", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "phone": { "description": "Phone number of the recipient", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "name": { "description": "Name of the recipient", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "orderInfo": { "anyOf": [ { "description": "Order information for this stop", "type": "object", "properties": { "products": { "description": "Products in this stop", "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "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", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "currency": { "description": "Currency of the payment. Defaults to the team's currency.", "anyOf": [ { "type": "string", "enum": [ "AED", "ARS", "AUD", "BRL", "CAD", "CHF", "CLP", "CNY", "COP", "DKK", "EGP", "EUR", "GBP", "HKD", "HUF", "ILS", "INR", "JPY", "KRW", "MYR", "MXN", "NOK", "NZD", "PEN", "RON", "RUB", "SAR", "SEK", "SGD", "TRY", "USD", "UYU", "ZAR" ] }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "proofOfAttemptRequirements": { "anyOf": [ { "description": "Proof of attempt requirement settings for this stop", "type": "object", "properties": { "enabled": { "description": "Whether proof of attempt is required for this stop", "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "allowedDrivers": { "description": "Driver IDs that are allowed to be assigned to this stop. These drivers must be configured as part of the plan to be valid.", "anyOf": [ { "maxItems": 100, "type": "array", "items": { "type": "string", "pattern": "^drivers\\/[a-zA-Z0-9---_]{1,50}$" } }, { "type": "null" } ] }, "activity": { "description": "Activity type", "default": "delivery", "anyOf": [ { "type": "string", "enum": [ "delivery", "pickup" ] }, { "type": "null" } ] }, "optimizationOrder": { "description": "The preferred order of this stop in the optimized route. If not provided or `\"default\"`, the stop will be placed in the optimal order, decided by the optimization algorithm. Otherwise it will be placed either `\"first\"` or `\"last\"`.", "anyOf": [ { "type": "string", "enum": [ "first", "last", "default" ] }, { "type": "null" } ] }, "packageCount": { "description": "Number of packages in the stop", "anyOf": [ { "type": "number", "minimum": 1, "maximum": 10000 }, { "type": "null" } ] }, "weight": { "description": "Weight information for this stop.", "anyOf": [ { "type": "object", "properties": { "amount": { "description": "The weight amount for this stop.", "type": "number", "minimum": 0, "maximum": 999999, "multipleOf": 0.01 }, "unit": { "description": "The weight unit in which the amount is specified.", "type": "string", "enum": [ "kilogram", "pound", "metric-ton" ] } }, "required": [ "amount", "unit" ] }, { "type": "null" } ] }, "notes": { "description": "Notes for the stop", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] }, "clientId": { "description": "Client ID of the retailer in Spoke Connect", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "barcodes": { "description": "List of barcode IDs associated with this stop", "maxItems": 50, "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, "description": "The request body for creating a stop. The only required field is address, you need to provide at least one of the fields in it. The latitude and longitude fields will override any of the other fields if they are set(and they need to be both set if any of them are). The more fields you provide the more accurate the geocoding will be." }, "parameters": [ { "schema": { "type": "string", "pattern": "^[a-zA-Z0-9---_]{1,50}$" }, "in": "path", "name": "planId", "required": true, "description": "The plan id" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "pending": { "type": "boolean" }, "stop": { "$ref": "#/components/schemas/stopSchema" } }, "required": [ "pending", "stop" ], "definitions": { "stopSchema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^plans\\/[a-zA-Z0-9---_]{1,50}\\/stops\\/[a-zA-Z0-9---_]{1,50}$", "description": "The id of the stop, in the format `plans//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." }, "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." }, "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": 1, "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" } }, "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" ], "additionalProperties": false, "description": "A stop of a plan, can be related to a route." } }, "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 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's optimization is in progress.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Plan optimization in progress" ] }, "code": { "type": "string", "enum": [ "plan_optimization_in_progress" ] } }, "required": [ "message", "code" ], "description": "The plan's optimization is in progress.", "title": "Plan optimization in progress" } } } }, "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}:liveUpdate": { "post": { "operationId": "updateLiveStop", "summary": "Update an existing stop", "tags": [ "Live Stops" ], "description": "Update a stop on live plans. When the plan is not writable, this endpoint starts an editing session and the action can be applied through a new optimization, or be discarded. It does not support updating a stop's location, nor the `clientId`. To do so, delete the stop and create a new one.", "requestBody": { "content": { "application/json": { "schema": { "description": "The request body for updating a stop. All the values present in the request will update the stop value, if you wish to update only certain fields, only set them and do not set the others. Any fields not set will not be updated.", "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", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "currency": { "description": "Currency of the payment. Defaults to the team's currency.", "anyOf": [ { "type": "string", "enum": [ "AED", "ARS", "AUD", "BRL", "CAD", "CHF", "CLP", "CNY", "COP", "DKK", "EGP", "EUR", "GBP", "HKD", "HUF", "ILS", "INR", "JPY", "KRW", "MYR", "MXN", "NOK", "NZD", "PEN", "RON", "RUB", "SAR", "SEK", "SGD", "TRY", "USD", "UYU", "ZAR" ] }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "proofOfAttemptRequirements": { "anyOf": [ { "description": "Proof of attempt requirement settings for this stop", "type": "object", "properties": { "enabled": { "description": "Whether proof of attempt is required for this stop", "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "allowedDrivers": { "description": "Driver IDs that are allowed to be assigned to this stop. These drivers must be configured as part of the plan to be valid.", "anyOf": [ { "maxItems": 100, "type": "array", "items": { "type": "string", "pattern": "^drivers\\/[a-zA-Z0-9---_]{1,50}$" } }, { "type": "null" } ] }, "activity": { "description": "Activity type", "default": "delivery", "anyOf": [ { "type": "string", "enum": [ "delivery", "pickup" ] }, { "type": "null" } ] }, "optimizationOrder": { "description": "The preferred order of this stop in the optimized route. If not provided or `\"default\"`, the stop will be placed in the optimal order, decided by the optimization algorithm. Otherwise it will be placed either `\"first\"` or `\"last\"`.", "anyOf": [ { "type": "string", "enum": [ "first", "last", "default" ] }, { "type": "null" } ] }, "packageCount": { "description": "Number of packages in the stop", "anyOf": [ { "type": "number", "minimum": 1, "maximum": 10000 }, { "type": "null" } ] }, "weight": { "description": "Weight information for this stop.", "anyOf": [ { "type": "object", "properties": { "amount": { "description": "The weight amount for this stop.", "type": "number", "minimum": 0, "maximum": 999999, "multipleOf": 0.01 }, "unit": { "description": "The weight unit in which the amount is specified.", "type": "string", "enum": [ "kilogram", "pound", "metric-ton" ] } }, "required": [ "amount", "unit" ] }, { "type": "null" } ] }, "notes": { "description": "Notes for the stop", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] }, "barcodes": { "description": "List of barcode IDs associated with this stop", "maxItems": 50, "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 } } }, "description": "The request body for updating a stop. All the values present in the request will update the stop value, if you wish to update only certain fields, only set them and do not set the others. Any fields not set will not be updated." }, "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": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "pending": { "type": "boolean" }, "stop": { "$ref": "#/components/schemas/stopSchema" } }, "required": [ "pending", "stop" ], "definitions": { "stopSchema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^plans\\/[a-zA-Z0-9---_]{1,50}\\/stops\\/[a-zA-Z0-9---_]{1,50}$", "description": "The id of the stop, in the format `plans//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." }, "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." }, "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": 1, "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" } }, "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" ], "additionalProperties": false, "description": "A stop of a plan, can be related to a route." } }, "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", "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's optimization is in progress.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Plan optimization in progress" ] }, "code": { "type": "string", "enum": [ "plan_optimization_in_progress" ] } }, "required": [ "message", "code" ], "description": "The plan's optimization is in progress.", "title": "Plan optimization in progress" } } } }, "412": { "description": "Drivers must be part of the plan to be referenced by stops", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Driver is not linked to plan" ] }, "param": { "type": "string", "description": "The parameter that caused the error." } }, "required": [ "message" ], "description": "Drivers must be part of the plan to be referenced by stops", "title": "Driver is not linked to plan" } } } }, "422": { "description": "The stop is unprocessable.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "message": { "anyOf": [ { "type": "string", "enum": [ "Stop cannot be edited" ] }, { "type": "string" } ] }, "code": { "type": "string", "enum": [ "stop_not_editable" ] } }, "required": [ "message", "code" ], "description": "Failed to update stop" }, { "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", "x-response-description": "Failed to create stop" } ], "description": "The stop is unprocessable." } } } }, "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:liveImport": { "post": { "operationId": "importLiveStops", "summary": "Batch import stops", "tags": [ "Live Stops" ], "description": "Import stops to live plans. When the plan is not writable, this endpoint starts an editing session and the action can be applied through a new optimization, or be discarded.", "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": { "description": "The request body for creating a stop. The only required field is address, you need to provide at least one of the fields in it. The latitude and longitude fields will override any of the other fields if they are set(and they need to be both set if any of them are). The more fields you provide the more accurate the geocoding will be.", "type": "object", "properties": { "address": { "type": "object", "properties": { "addressName": { "description": "The name of the address. This will not be used for geocoding, and is only for the final address display purposes.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "addressLineOne": { "description": "The first line of the address.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "addressLineTwo": { "description": "The second line of the address.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "city": { "description": "The city of the address.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "state": { "description": "The state of the address.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "zip": { "description": "The zip code of the address.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "country": { "description": "The country of the address.", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "latitude": { "description": "The latitude of the address in decimal degrees.", "anyOf": [ { "type": "number", "minimum": -90, "maximum": 90 }, { "type": "null" } ] }, "longitude": { "description": "The longitude of the address in decimal degrees.", "anyOf": [ { "type": "number", "minimum": -180, "maximum": 180 }, { "type": "null" } ] } }, "additionalProperties": false }, "timing": { "anyOf": [ { "description": "Timing information for this stop", "type": "object", "properties": { "earliestAttemptTime": { "description": "Time of day of the earliest time this stop should happen", "anyOf": [ { "description": "Time of day in hours and minutes. Use a 24 hour clock.", "type": "object", "properties": { "hour": { "description": "Hour of the day", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "minute": { "description": "Minute of the hour", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "hour", "minute" ], "additionalProperties": false }, { "type": "null" } ] }, "latestAttemptTime": { "description": "Time of day of the latest time this stop should happen", "anyOf": [ { "description": "Time of day in hours and minutes. Use a 24 hour clock.", "type": "object", "properties": { "hour": { "description": "Hour of the day", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "minute": { "description": "Minute of the hour", "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "hour", "minute" ], "additionalProperties": false }, { "type": "null" } ] }, "estimatedAttemptDuration": { "description": "Duration in seconds of the activity in this stop, only set if you want to override the default. This can be set up to 8 hours.", "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "recipient": { "anyOf": [ { "description": "Recipient information for this stop", "type": "object", "properties": { "externalId": { "description": "External ID of the recipient, as defined by the API user", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "email": { "description": "Email of the recipient", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "phone": { "description": "Phone number of the recipient", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "name": { "description": "Name of the recipient", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "orderInfo": { "anyOf": [ { "description": "Order information for this stop", "type": "object", "properties": { "products": { "description": "Products in this stop", "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }, "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", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "currency": { "description": "Currency of the payment. Defaults to the team's currency.", "anyOf": [ { "type": "string", "enum": [ "AED", "ARS", "AUD", "BRL", "CAD", "CHF", "CLP", "CNY", "COP", "DKK", "EGP", "EUR", "GBP", "HKD", "HUF", "ILS", "INR", "JPY", "KRW", "MYR", "MXN", "NOK", "NZD", "PEN", "RON", "RUB", "SAR", "SEK", "SGD", "TRY", "USD", "UYU", "ZAR" ] }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "proofOfAttemptRequirements": { "anyOf": [ { "description": "Proof of attempt requirement settings for this stop", "type": "object", "properties": { "enabled": { "description": "Whether proof of attempt is required for this stop", "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "allowedDrivers": { "description": "Driver IDs that are allowed to be assigned to this stop. These drivers must be configured as part of the plan to be valid.", "anyOf": [ { "maxItems": 100, "type": "array", "items": { "type": "string", "pattern": "^drivers\\/[a-zA-Z0-9---_]{1,50}$" } }, { "type": "null" } ] }, "activity": { "description": "Activity type", "default": "delivery", "anyOf": [ { "type": "string", "enum": [ "delivery", "pickup" ] }, { "type": "null" } ] }, "optimizationOrder": { "description": "The preferred order of this stop in the optimized route. If not provided or `\"default\"`, the stop will be placed in the optimal order, decided by the optimization algorithm. Otherwise it will be placed either `\"first\"` or `\"last\"`.", "anyOf": [ { "type": "string", "enum": [ "first", "last", "default" ] }, { "type": "null" } ] }, "packageCount": { "description": "Number of packages in the stop", "anyOf": [ { "type": "number", "minimum": 1, "maximum": 10000 }, { "type": "null" } ] }, "weight": { "description": "Weight information for this stop.", "anyOf": [ { "type": "object", "properties": { "amount": { "description": "The weight amount for this stop.", "type": "number", "minimum": 0, "maximum": 999999, "multipleOf": 0.01 }, "unit": { "description": "The weight unit in which the amount is specified.", "type": "string", "enum": [ "kilogram", "pound", "metric-ton" ] } }, "required": [ "amount", "unit" ] }, { "type": "null" } ] }, "notes": { "description": "Notes for the stop", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] }, "clientId": { "description": "Client ID of the retailer in Spoke Connect", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "barcodes": { "description": "List of barcode IDs associated with this stop", "maxItems": 50, "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" }, "pending": { "type": "boolean" } }, "required": [ "success", "failed", "pending" ], "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's optimization is in progress.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Plan optimization in progress" ] }, "code": { "type": "string", "enum": [ "plan_optimization_in_progress" ] } }, "required": [ "message", "code" ], "description": "The plan's optimization is in progress.", "title": "Plan optimization in progress" } } } }, "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}:liveDelete": { "post": { "operationId": "deleteLiveStop", "summary": "Delete a stop", "tags": [ "Live Stops" ], "description": "Delete a stop on live plans. When the plan is not writable, this endpoint starts an editing session and the action can be applied through a new optimization, or be discarded.", "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": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "pending": { "type": "boolean" } }, "required": [ "pending" ], "description": "Success" } } } }, "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's optimization is in progress.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Plan optimization in progress" ] }, "code": { "type": "string", "enum": [ "plan_optimization_in_progress" ] } }, "required": [ "message", "code" ], "description": "The plan's optimization is in progress.", "title": "Plan optimization in progress" } } } }, "422": { "description": "Failed to delete stop", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "anyOf": [ { "type": "string", "enum": [ "Stop cannot be removed because it is already complete" ] }, { "type": "string" } ] } }, "required": [ "message" ], "description": "Failed to delete 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" } } } } } } }, "/drivers": { "get": { "operationId": "listDrivers", "summary": "List Drivers", "tags": [ "Drivers" ], "parameters": [ { "schema": { "default": 50, "type": "number", "minimum": 1, "maximum": 50 }, "in": "query", "name": "maxPageSize", "required": false, "description": "The maximum number of drivers to return." }, { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "in": "query", "name": "pageToken", "required": false, "description": "The page token to continue from." }, { "schema": { "type": "object", "properties": { "active": { "description": "Filter by the active status of the driver. Inactive drivers will not be assigned to any routes.", "type": "string", "enum": [ "true", "false" ] } }, "additionalProperties": false }, "in": "query", "name": "filter", "required": false, "description": "The filter to apply to the list of drivers. The filter param is passed like this: `?filter[active]=true` or like this: `?filter.active=true`" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "drivers": { "type": "array", "items": { "$ref": "#/components/schemas/driverSchema" }, "description": "The drivers." }, "nextPageToken": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The next page token." } }, "required": [ "drivers", "nextPageToken" ], "definitions": { "driverSchema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^drivers\\/[a-zA-Z0-9---_]{1,50}$", "description": "The driver id, in the format `drivers/`" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The name of the driver." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The email of the driver." }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The phone number of the driver." }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The display name of the driver." }, "active": { "type": "boolean", "description": "Whether the driver membership is active or paused. Paused drivers will not be assigned to any routes." }, "depots": { "type": "array", "items": { "type": "string", "pattern": "^depots\\/[a-zA-Z0-9---_]{1,50}$" }, "description": "Depots associated with the driver." }, "routeOverrides": { "type": "object", "properties": { "startTime": { "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": "Driver's start time." }, "endTime": { "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": "Driver's end time." }, "startAddress": { "anyOf": [ { "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." }, { "type": "null" } ], "description": "Driver's start location." }, "endAddress": { "anyOf": [ { "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." }, { "type": "null" } ], "description": "Driver's end location." }, "maxStops": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Maximum number of Stops the Driver can take in a route." }, "drivingSpeed": { "type": "string", "enum": [ "slower", "average", "faster" ], "description": "The relative driving speed of the driver compared to others." }, "deliverySpeed": { "type": "string", "enum": [ "slower", "average", "faster" ], "description": "The relative delivery speed of the driver compared to others." }, "vehicleType": { "anyOf": [ { "type": "string", "enum": [ "bike", "scooter", "car", "small_truck", "truck", "electric_cargo_bike" ] }, { "type": "null" } ], "description": "The vehicle type the driver will be using for deliveries." } }, "required": [ "startTime", "endTime", "startAddress", "endAddress", "maxStops", "drivingSpeed", "deliverySpeed", "vehicleType" ], "description": "Settings to override default route settings." } }, "required": [ "id", "name", "email", "phone", "displayName", "active", "depots", "routeOverrides" ], "additionalProperties": false, "description": "A driver." } }, "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" } } } }, "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" } } } } } }, "post": { "operationId": "createDriver", "summary": "Create a new driver", "tags": [ "Drivers" ], "description": "Create a driver with the given data in your team. Prefer using the [batch import endpoint](#operation/importDrivers) for creating multiple drivers at once as it is more efficient, faster.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The driver's full name", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "displayName": { "description": "The name displayed for the driver in the UI", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "email": { "description": "Driver's email", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "phone": { "description": "Driver's phone number", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "depots": { "description": "The depot IDs associated with the driver in the format `depots/`, duplicates will be ignored. If set to null or not provided, the team's Main depot will be set as driver depot.", "anyOf": [ { "minItems": 1, "maxItems": 50, "type": "array", "items": { "description": "The depot ID, in the format `depots/`", "type": "string", "pattern": "^depots\\/[a-zA-Z0-9---_]{1,50}$" } }, { "type": "null" } ] }, "routeOverrides": { "description": "Overrides for the driver route behavior.", "anyOf": [ { "type": "object", "properties": { "startAddress": { "description": "Address of a start location for every route assigned to this driver. If the latitude and longitude fields are set they will override any of the others. The addressName field is not used for geocoding and is only for display purposes.", "anyOf": [ { "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 }, { "type": "null" } ] }, "endAddress": { "description": "Address of an end location for every route assigned to this driver. If the latitude and longitude fields are set they will override any of the others. The addressName field is not used for geocoding and is only for display purposes.", "anyOf": [ { "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 }, { "type": "null" } ] }, "startTime": { "description": "The start time for the driver's work day.", "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" } ] }, "endTime": { "description": "The end time for the driver's work day.", "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" } ] }, "maxStops": { "description": "The maximum number of stops that can be allocated to this driver.", "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "drivingSpeed": { "anyOf": [ { "default": "average", "description": "How fast this driver drives compared to the Team's average", "type": "string", "enum": [ "slower", "average", "faster" ] }, { "type": "null" } ] }, "deliverySpeed": { "description": "How fast this driver delivers compared to the Team's average", "anyOf": [ { "default": "average", "type": "string", "enum": [ "slower", "average", "faster" ] }, { "type": "null" } ] }, "vehicleType": { "description": "The type of vehicle used by this driver", "anyOf": [ { "type": "string", "enum": [ "bike", "scooter", "car", "small_truck", "truck", "electric_cargo_bike" ] }, { "type": "null" } ] } } }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "The created driver", "content": { "application/json": { "schema": { "description": "The created driver", "$ref": "#/components/schemas/driverSchema" } } } }, "400": { "description": "Failed to validate the request", "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": "Failed to validate the request" } } } }, "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" } } } }, "422": { "description": "Failed to create driver.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "anyOf": [ { "type": "string", "enum": [ "An error occured when creating the driver, 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 driver." } } } }, "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" } } } } } } }, "/drivers/{driverId}": { "get": { "operationId": "getDriver", "summary": "Retrieve a driver", "tags": [ "Drivers" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-zA-Z0-9---_]{1,50}$" }, "in": "path", "name": "driverId", "required": true, "description": "The driver id" } ], "responses": { "200": { "description": "The requested driver", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/driverSchema", "description": "The requested driver" } } } }, "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" } } } }, "404": { "description": "The provided driver id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "anyOf": [ { "type": "string", "enum": [ "Driver not found" ] }, { "type": "string" } ] } }, "required": [ "message" ], "description": "The provided driver id does not exist", "title": "Driver 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": "deleteDriver", "summary": "Remove a driver", "tags": [ "Drivers" ], "description": "Removes a driver from your team. If the driver also has dashboard access, the driver will only have their \"driver\" role revoked; thus not being listed among the team drivers, but will keep their dashboard access.", "parameters": [ { "schema": { "type": "string", "pattern": "^[a-zA-Z0-9---_]{1,50}$" }, "in": "path", "name": "driverId", "required": true, "description": "The driver id" } ], "responses": { "204": { "description": "Driver removed 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" } } } }, "404": { "description": "The provided driver id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "anyOf": [ { "type": "string", "enum": [ "Driver not found" ] }, { "type": "string" } ] } }, "required": [ "message" ], "description": "The provided driver id does not exist", "title": "Driver 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" } } } } } }, "patch": { "operationId": "updateDriver", "summary": "Update a driver", "tags": [ "Drivers" ], "description": "Updates a driver from your team. The member must have the \"driver\" role.", "requestBody": { "content": { "application/json": { "schema": { "description": "The request body for updating a driver.", "type": "object", "properties": { "name": { "description": "The driver's full name", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "displayName": { "description": "The name displayed for the driver in the UI", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "depots": { "description": "The depot IDs associated with the driver in the format `depots/`, duplicates will be ignored. If set to null or not provided, the team's Main depot will be set as driver depot.", "anyOf": [ { "minItems": 1, "maxItems": 50, "type": "array", "items": { "description": "The depot ID, in the format `depots/`", "type": "string", "pattern": "^depots\\/[a-zA-Z0-9---_]{1,50}$" } }, { "type": "null" } ] }, "routeOverrides": { "description": "Overrides for the driver route behavior.", "anyOf": [ { "type": "object", "properties": { "startAddress": { "description": "Address of a start location for every route assigned to this driver. If the latitude and longitude fields are set they will override any of the others. The addressName field is not used for geocoding and is only for display purposes.", "anyOf": [ { "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 }, { "type": "null" } ] }, "endAddress": { "description": "Address of an end location for every route assigned to this driver. If the latitude and longitude fields are set they will override any of the others. The addressName field is not used for geocoding and is only for display purposes.", "anyOf": [ { "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 }, { "type": "null" } ] }, "startTime": { "description": "The start time for the driver's work day.", "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" } ] }, "endTime": { "description": "The end time for the driver's work day.", "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" } ] }, "maxStops": { "description": "The maximum number of stops that can be allocated to this driver.", "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "drivingSpeed": { "anyOf": [ { "default": "average", "description": "How fast this driver drives compared to the Team's average", "type": "string", "enum": [ "slower", "average", "faster" ] }, { "type": "null" } ] }, "deliverySpeed": { "description": "How fast this driver delivers compared to the Team's average", "anyOf": [ { "default": "average", "type": "string", "enum": [ "slower", "average", "faster" ] }, { "type": "null" } ] }, "vehicleType": { "description": "The type of vehicle used by this driver", "anyOf": [ { "type": "string", "enum": [ "bike", "scooter", "car", "small_truck", "truck", "electric_cargo_bike" ] }, { "type": "null" } ] } } }, { "type": "null" } ] } }, "additionalProperties": false } } }, "description": "The request body for updating a driver." }, "parameters": [ { "schema": { "type": "string", "pattern": "^[a-zA-Z0-9---_]{1,50}$" }, "in": "path", "name": "driverId", "required": true, "description": "The driver id" } ], "responses": { "200": { "description": "The updated driver", "content": { "application/json": { "schema": { "description": "The updated driver", "$ref": "#/components/schemas/driverSchema" } } } }, "400": { "description": "Failed to validate the request", "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": "Failed to validate the request" } } } }, "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" } } } }, "422": { "description": "Failed to update driver", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "anyOf": [ { "type": "string", "enum": [ "An error occured when updating the driver, 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 update driver" } } } }, "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" } } } } } } }, "/drivers:import": { "post": { "operationId": "importDrivers", "summary": "Batch import drivers", "tags": [ "Drivers" ], "description": "Creates multiple drivers in your team. The request body must contain an array of drivers to import.", "requestBody": { "content": { "application/json": { "schema": { "description": "An array of driver descriptions to be created in batch.", "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "name": { "description": "The driver's full name", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "displayName": { "description": "The name displayed for the driver in the UI", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "email": { "description": "Driver's email", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "phone": { "description": "Driver's phone number", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "depots": { "description": "The depot IDs associated with the driver in the format `depots/`, duplicates will be ignored. If set to null or not provided, the team's Main depot will be set as driver depot.", "anyOf": [ { "minItems": 1, "maxItems": 50, "type": "array", "items": { "description": "The depot ID, in the format `depots/`", "type": "string", "pattern": "^depots\\/[a-zA-Z0-9---_]{1,50}$" } }, { "type": "null" } ] }, "routeOverrides": { "description": "Overrides for the driver route behavior.", "anyOf": [ { "type": "object", "properties": { "startAddress": { "description": "Address of a start location for every route assigned to this driver. If the latitude and longitude fields are set they will override any of the others. The addressName field is not used for geocoding and is only for display purposes.", "anyOf": [ { "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 }, { "type": "null" } ] }, "endAddress": { "description": "Address of an end location for every route assigned to this driver. If the latitude and longitude fields are set they will override any of the others. The addressName field is not used for geocoding and is only for display purposes.", "anyOf": [ { "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 }, { "type": "null" } ] }, "startTime": { "description": "The start time for the driver's work day.", "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" } ] }, "endTime": { "description": "The end time for the driver's work day.", "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" } ] }, "maxStops": { "description": "The maximum number of stops that can be allocated to this driver.", "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "drivingSpeed": { "anyOf": [ { "default": "average", "description": "How fast this driver drives compared to the Team's average", "type": "string", "enum": [ "slower", "average", "faster" ] }, { "type": "null" } ] }, "deliverySpeed": { "description": "How fast this driver delivers compared to the Team's average", "anyOf": [ { "default": "average", "type": "string", "enum": [ "slower", "average", "faster" ] }, { "type": "null" } ] }, "vehicleType": { "description": "The type of vehicle used by this driver", "anyOf": [ { "type": "string", "enum": [ "bike", "scooter", "car", "small_truck", "truck", "electric_cargo_bike" ] }, { "type": "null" } ] } } }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "description": "An array of driver descriptions to be created in batch." }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "array", "items": { "type": "string", "pattern": "^drivers\\/[a-zA-Z0-9---_]{1,50}$", "description": "The id of the driver, in the format `drivers/`." }, "description": "The ids of the successfully imported drivers" }, "failed": { "type": "array", "items": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "description": "The error that occurred during import" } }, "required": [ "message" ] }, "driver": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "The driver's full name" }, "displayName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "The name displayed for the driver in the UI" }, "email": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ], "description": "Driver's email" }, "phone": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "Driver's phone number" }, "depots": { "anyOf": [ { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "pattern": "^depots\\/[a-zA-Z0-9---_]{1,50}$", "description": "The depot ID, in the format `depots/`" } }, { "type": "null" } ], "description": "The depot IDs associated with the driver in the format `depots/`, duplicates will be ignored. If set to null or not provided, the team's Main depot will be set as driver depot." }, "routeOverrides": { "anyOf": [ { "type": "object", "properties": { "startAddress": { "anyOf": [ { "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." } }, "additionalProperties": false }, { "type": "null" } ], "description": "Address of a start location for every route assigned to this driver. If the latitude and longitude fields are set they will override any of the others. The addressName field is not used for geocoding and is only for display purposes." }, "endAddress": { "anyOf": [ { "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." } }, "additionalProperties": false }, { "type": "null" } ], "description": "Address of an end location for every route assigned to this driver. If the latitude and longitude fields are set they will override any of the others. The addressName field is not used for geocoding and is only for display purposes." }, "startTime": { "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. Use a 24 hour clock." }, { "type": "null" } ], "description": "The start time for the driver's work day." }, "endTime": { "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. Use a 24 hour clock." }, { "type": "null" } ], "description": "The end time for the driver's work day." }, "maxStops": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "The maximum number of stops that can be allocated to this driver." }, "drivingSpeed": { "anyOf": [ { "default": "average", "type": "string", "enum": [ "slower", "average", "faster" ], "description": "How fast this driver drives compared to the Team's average" }, { "type": "null" } ] }, "deliverySpeed": { "anyOf": [ { "default": "average", "type": "string", "enum": [ "slower", "average", "faster" ] }, { "type": "null" } ], "description": "How fast this driver delivers compared to the Team's average" }, "vehicleType": { "anyOf": [ { "type": "string", "enum": [ "bike", "scooter", "car", "small_truck", "truck", "electric_cargo_bike" ] }, { "type": "null" } ], "description": "The type of vehicle used by this driver" } } }, { "type": "null" } ] } }, "description": "The request body for creating a driver. Even though `email` and `phone` are optional, you must provide at least one of" } }, "required": [ "error", "driver" ] }, "description": "The failed drivers" } }, "required": [ "success", "failed" ], "description": "Success" } } } }, "400": { "description": "Failed to validate the request", "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": "Failed to validate the request" } } } }, "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" } } } }, "422": { "description": "Failed to import drivers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "anyOf": [ { "type": "string", "enum": [ "An error occured when importing drivers, 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 import drivers." } } } }, "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" } } } } } } }, "/depots": { "post": { "operationId": "createDepot", "summary": "Create a depot", "tags": [ "Depots" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 2048 }, "routeOverrides": { "description": "Defines some default parameters for routes originating from this depot", "type": "object", "properties": { "startAddress": { "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 }, "startTime": { "description": "Route start time", "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 }, "endAddress": { "anyOf": [ { "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 }, { "type": "null" } ] }, "endTime": { "anyOf": [ { "description": "Time of day in hours and minutes. Uses 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" } ] }, "defaultTimeAtStop": { "anyOf": [ { "description": "Estimated time at the stop", "type": "number" }, { "type": "null" } ] }, "maxStops": { "anyOf": [ { "description": "Maximum number of stops per driver", "type": "number" }, { "type": "null" } ] }, "vehicleType": { "anyOf": [ { "description": "Default vehicle type", "type": "string", "enum": [ "bike", "scooter", "car", "small_truck", "truck", "electric_cargo_bike" ] }, { "type": "null" } ] }, "roadSide": { "anyOf": [ { "description": "Attempt to visit stops on this side of the road", "type": "string", "enum": [ "any", "left_only", "right_only" ] }, { "type": "null" } ] }, "roundTrip": { "anyOf": [ { "description": "Return to the startAddress at the end of the route", "type": "boolean" }, { "type": "null" } ] } }, "required": [ "startAddress", "startTime" ] } }, "required": [ "name", "routeOverrides" ], "additionalProperties": false } } }, "required": true }, "responses": { "200": { "description": "The requested depot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/depotSchema", "description": "The requested depot" } } } }, "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" }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": [ "message", "param" ], "description": "A provided route override parameter was invalid.", "title": "Route override was invalid" } ], "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" } } } } } }, "get": { "operationId": "listDepots", "summary": "List Depots", "tags": [ "Depots" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "in": "query", "name": "pageToken", "required": false, "description": "The page token to continue from." }, { "schema": { "default": 20, "type": "number", "minimum": 1, "maximum": 20 }, "in": "query", "name": "maxPageSize", "required": false, "description": "The maximum number of depots to return." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "depots": { "type": "array", "items": { "$ref": "#/components/schemas/depotSchema" }, "description": "The depots." }, "nextPageToken": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The next page token." } }, "required": [ "depots", "nextPageToken" ], "definitions": { "depotSchema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^depots\\/[a-zA-Z0-9---_]{1,50}$", "description": "The depot id, in the format `depots/`" }, "name": { "type": "string", "description": "The name of the depot." }, "routeOverrides": { "anyOf": [ { "type": "object", "properties": { "startTime": { "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": "Default route start time." }, "startAddress": { "type": "object", "properties": { "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The full address." }, "addressLineOne": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The first line of the address." }, "addressLineTwo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The second line of the address." }, "latitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Latitude coordinate of the depot in decimal degrees." }, "longitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Longitude coordinate of the depot in decimal degrees." }, "placeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A Google PlaceID identifying the location of the depot." }, "countryCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The country code of the address." } }, "required": [ "address", "addressLineOne", "addressLineTwo", "latitude", "longitude", "placeId", "countryCode" ], "description": "The default start address for routes originating from this depot." }, "defaultTimeAtStop": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Estimated time at stop in seconds." }, "endAddress": { "anyOf": [ { "type": "object", "properties": { "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The full address." }, "addressLineOne": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The first line of the address." }, "addressLineTwo": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The second line of the address." }, "latitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Latitude coordinate of the depot in decimal degrees." }, "longitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Longitude coordinate of the depot in decimal degrees." }, "placeId": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "A Google PlaceID identifying the location of the depot." }, "countryCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The country code of the address." } }, "required": [ "address", "addressLineOne", "addressLineTwo", "latitude", "longitude", "placeId", "countryCode" ], "description": "The default end address for routes originating from this depot (if empty, assume a round-trip)." }, { "type": "null" } ] }, "endTime": { "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": "Default route end time." }, { "type": "null" } ] }, "maxStops": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Max stops assigned to each driver" }, "roadSide": { "anyOf": [ { "type": "string", "enum": [ "any", "left_only", "right_only" ] }, { "type": "null" } ], "description": "The side of the road drivers should stop at." }, "vehicleType": { "anyOf": [ { "type": "string", "enum": [ "bike", "scooter", "car", "small_truck", "truck", "electric_cargo_bike" ] }, { "type": "null" } ], "description": "Default vehicle type for new routes from this depot." }, "roundTrip": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Return to start address at end of route" } }, "required": [ "startTime", "startAddress" ] }, { "type": "null" } ] } }, "required": [ "id", "name", "routeOverrides" ], "additionalProperties": false, "description": "A depot." } }, "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" } } } }, "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" } } } } } } }, "/depots/{depotId}": { "get": { "operationId": "getDepot", "summary": "Retrieve a depot", "tags": [ "Depots" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-zA-Z0-9---_]{1,50}$" }, "in": "path", "name": "depotId", "required": true, "description": "The depot id" } ], "responses": { "200": { "description": "The requested depot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/depotSchema", "description": "The requested depot" } } } }, "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" } } } }, "404": { "description": "The provided depot id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Depot not found" ] } }, "required": [ "message" ], "description": "The provided depot id does not exist", "title": "Depot 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": "deleteDepot", "summary": "Remove a depot", "tags": [ "Depots" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-zA-Z0-9---_]{1,50}$" }, "in": "path", "name": "depotId", "required": true, "description": "The depot id" } ], "responses": { "204": { "description": "Depot removed successfully" }, "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", "enum": [ "Depot cannot be deleted" ] } }, "required": [ "message" ], "description": "The depot cannot be deleted because because a pre-condition was not met", "title": "Depot cannot be deleted" } ], "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" } } } } } }, "patch": { "operationId": "updateDepot", "summary": "Update a depot", "tags": [ "Depots" ], "requestBody": { "content": { "application/json": { "schema": { "description": "The request body for updating a depot. All the values present in the request will update the depot value; if you wish to update only certain fields, only set them and do not set the others. Any fields not set will not be updated.", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 2048 }, "routeOverrides": { "type": "object", "properties": { "startAddress": { "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 }, "startTime": { "description": "Route start time", "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 }, "endAddress": { "anyOf": [ { "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 }, { "type": "null" } ] }, "endTime": { "anyOf": [ { "description": "Time of day in hours and minutes. Uses 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" } ] }, "defaultTimeAtStop": { "anyOf": [ { "description": "Estimated time at the stop", "type": "number" }, { "type": "null" } ] }, "maxStops": { "anyOf": [ { "description": "Maximum number of stops per driver", "type": "number" }, { "type": "null" } ] }, "vehicleType": { "anyOf": [ { "description": "Default vehicle type", "type": "string", "enum": [ "bike", "scooter", "car", "small_truck", "truck", "electric_cargo_bike" ] }, { "type": "null" } ] }, "roadSide": { "anyOf": [ { "description": "Attempt to visit stops on this side of the road", "type": "string", "enum": [ "any", "left_only", "right_only" ] }, { "type": "null" } ] }, "roundTrip": { "anyOf": [ { "description": "Return to the startAddress at the end of the route", "type": "boolean" }, { "type": "null" } ] } } } }, "additionalProperties": false } } }, "description": "The request body for updating a depot. All the values present in the request will update the depot value; if you wish to update only certain fields, only set them and do not set the others. Any fields not set will not be updated." }, "parameters": [ { "schema": { "type": "string", "pattern": "^[a-zA-Z0-9---_]{1,50}$" }, "in": "path", "name": "depotId", "required": true, "description": "The depot id" } ], "responses": { "200": { "description": "The updated depot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/depotSchema", "description": "The updated depot" } } } }, "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" }, "url": { "type": "string", "description": "The URL with more information about the error." } }, "required": [ "message", "param" ], "description": "A provided route override parameter was invalid.", "title": "Route override was invalid" } ], "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" } } } }, "404": { "description": "The provided depot id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Depot not found" ] } }, "required": [ "message" ], "description": "The provided depot id does not exist", "title": "Depot 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" } } } } } } }, "/depots:import": { "post": { "operationId": "importDepots", "summary": "Batch import depots", "tags": [ "Depots" ], "description": "Batch import depots. The request body must contain an array of depots to import.", "requestBody": { "content": { "application/json": { "schema": { "description": "An array of depots to import in batch. Supports a maximum of 100 depots per request.", "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 2048 }, "routeOverrides": { "description": "Defines some default parameters for routes originating from this depot", "type": "object", "properties": { "startAddress": { "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 }, "startTime": { "description": "Route start time", "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 }, "endAddress": { "anyOf": [ { "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 }, { "type": "null" } ] }, "endTime": { "anyOf": [ { "description": "Time of day in hours and minutes. Uses 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" } ] }, "defaultTimeAtStop": { "anyOf": [ { "description": "Estimated time at the stop", "type": "number" }, { "type": "null" } ] }, "maxStops": { "anyOf": [ { "description": "Maximum number of stops per driver", "type": "number" }, { "type": "null" } ] }, "vehicleType": { "anyOf": [ { "description": "Default vehicle type", "type": "string", "enum": [ "bike", "scooter", "car", "small_truck", "truck", "electric_cargo_bike" ] }, { "type": "null" } ] }, "roadSide": { "anyOf": [ { "description": "Attempt to visit stops on this side of the road", "type": "string", "enum": [ "any", "left_only", "right_only" ] }, { "type": "null" } ] }, "roundTrip": { "anyOf": [ { "description": "Return to the startAddress at the end of the route", "type": "boolean" }, { "type": "null" } ] } }, "required": [ "startAddress", "startTime" ] } }, "required": [ "name", "routeOverrides" ], "additionalProperties": false } } } }, "description": "An array of depots to import in batch. Supports a maximum of 100 depots per request." }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "array", "items": { "type": "string", "pattern": "^depots\\/[a-zA-Z0-9---_]{1,50}$", "description": "The id of the depot, in the format `depots/`." }, "description": "The ids of the successfully imported depots" }, "failed": { "type": "array", "items": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "description": "The error that occurred during import" } }, "required": [ "message" ] }, "depot": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 2048 }, "routeOverrides": { "type": "object", "properties": { "startAddress": { "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." } }, "additionalProperties": false }, "startTime": { "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": "Route start time" }, "endAddress": { "anyOf": [ { "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." } }, "additionalProperties": false }, { "type": "null" } ] }, "endTime": { "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 }, { "type": "null" } ], "description": "Route end time" }, "defaultTimeAtStop": { "anyOf": [ { "type": "number", "description": "Estimated time at the stop" }, { "type": "null" } ] }, "maxStops": { "anyOf": [ { "type": "number", "description": "Maximum number of stops per driver" }, { "type": "null" } ] }, "vehicleType": { "anyOf": [ { "type": "string", "enum": [ "bike", "scooter", "car", "small_truck", "truck", "electric_cargo_bike" ], "description": "Default vehicle type" }, { "type": "null" } ] }, "roadSide": { "anyOf": [ { "type": "string", "enum": [ "any", "left_only", "right_only" ], "description": "Attempt to visit stops on this side of the road" }, { "type": "null" } ] }, "roundTrip": { "anyOf": [ { "type": "boolean", "description": "Return to the startAddress at the end of the route" }, { "type": "null" } ] } }, "required": [ "startAddress", "startTime" ] } }, "required": [ "name", "routeOverrides" ], "additionalProperties": false, "description": "The depot that failed to import" } }, "required": [ "error", "depot" ] }, "description": "The failed depots" } }, "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" } } } }, "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" } } } } } } }, "/depots/{depotId}:setMain": { "post": { "operationId": "setMainDepot", "summary": "Set the main depot for the team", "tags": [ "Depots" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-zA-Z0-9---_]{1,50}$" }, "in": "path", "name": "depotId", "required": true, "description": "The depot id" } ], "responses": { "204": { "description": "Depot set as main successfully" }, "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" } } } }, "404": { "description": "The provided depot id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Depot not found" ] } }, "required": [ "message" ], "description": "The provided depot id does not exist", "title": "Depot 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" } } } } } } }, "/routes/{routeId}": { "get": { "operationId": "getRoute", "summary": "Retrieve a route", "tags": [ "Routes" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-zA-Z0-9---_]{1,50}$" }, "in": "path", "name": "routeId", "required": true, "description": "The route id" } ], "responses": { "200": { "description": "The requested route", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/routeSchema", "description": "The requested route" } } } }, "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": "Route is no longer accessible due to data access restrictions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Route is no longer accessible due to data access restrictions." ] }, "code": { "type": "string", "enum": [ "route_inaccessible" ] } }, "required": [ "message", "code" ], "description": "Route is no longer accessible due to data access restrictions." } } } }, "404": { "description": "The provided route id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Route not found" ] } }, "required": [ "message" ], "description": "The provided route id does not exist" } } } }, "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" } } } } } } }, "/routes": { "get": { "operationId": "listRoutes", "summary": "List Routes", "tags": [ "Routes" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "in": "query", "name": "pageToken", "required": false, "description": "The page token to continue from." }, { "schema": { "default": 20, "type": "number", "minimum": 1, "maximum": 20 }, "in": "query", "name": "maxPageSize", "required": false, "description": "The maximum number of routes to return." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "routes": { "type": "array", "items": { "$ref": "#/components/schemas/routeSchema" }, "description": "The routes." }, "nextPageToken": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The next page token." } }, "required": [ "routes", "nextPageToken" ], "definitions": { "routeSchema": { "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." } }, "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" } } } }, "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" } } } } } } }, "/routes/{routeId}/stops": { "get": { "operationId": "listRouteStops", "summary": "List route stops", "tags": [ "Routes" ], "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": "routeId", "required": true, "description": "The route 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." }, "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." }, "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." }, "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": 1, "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" } }, "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" ], "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": "Route is no longer accessible due to data access restrictions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Route is no longer accessible due to data access restrictions." ] }, "code": { "type": "string", "enum": [ "route_inaccessible" ] } }, "required": [ "message", "code" ], "description": "Route is no longer accessible due to data access restrictions." } } } }, "404": { "description": "The provided route id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Route not found" ] } }, "required": [ "message" ], "description": "The provided route id does not exist" } } } }, "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" } } } } } } }, "/operations/{operationId}:cancel": { "post": { "operationId": "cancelOperation", "summary": "Cancel an operation", "tags": [ "Operations" ], "description": "Cancel an operation that is not yet done.", "parameters": [ { "schema": { "type": "string", "pattern": "^[a-zA-Z0-9---_]{1,50}$" }, "in": "path", "name": "operationId", "required": true, "description": "The ID of the operation to cancel." } ], "responses": { "200": { "description": "The operation was canceled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/operationSchema", "description": "The operation was canceled 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" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "The operation was not found." ] }, "code": { "type": "string", "enum": [ "operation_not_found" ] } }, "required": [ "message", "code" ], "description": "Not Found" } } } }, "409": { "description": "Client Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "The operation cannot be canceled because it is already done." ] }, "code": { "type": "string", "enum": [ "operation_already_done" ] } }, "required": [ "message", "code" ], "description": "Client Error" } } } }, "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" } } } } } } }, "/operations/{operationId}": { "get": { "operationId": "getOperation", "summary": "Retrieve an operation", "tags": [ "Operations" ], "parameters": [ { "schema": { "type": "string", "pattern": "^[a-zA-Z0-9---_]{1,50}$" }, "in": "path", "name": "operationId", "required": true, "description": "The ID of the operation to cancel." } ], "responses": { "200": { "description": "The requested operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/operationSchema", "description": "The requested operation" } } } }, "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" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "The operation was not found." ] }, "code": { "type": "string", "enum": [ "operation_not_found" ] } }, "required": [ "message", "code" ], "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" } } } } } } }, "/operations": { "get": { "operationId": "listOperations", "summary": "List operations", "tags": [ "Operations" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "in": "query", "name": "pageToken", "required": false, "description": "The page token to continue from." }, { "schema": { "default": 20, "type": "number", "minimum": 1, "maximum": 20 }, "in": "query", "name": "maxPageSize", "required": false, "description": "The maximum number of operations to return per page." }, { "schema": { "type": "object", "properties": { "done": { "description": "Filter by whether the operation is done.", "anyOf": [ { "type": "string", "enum": [ "true" ] }, { "type": "string", "enum": [ "false" ] } ] }, "type": { "description": "The type of the operation. Use this to filter which operations to get when listing operations. If not specified, all operations are returned. If specified, only operations of the specified type are returned.", "type": "string", "enum": [ "plan_optimization" ] } } }, "in": "query", "name": "filter", "required": false, "description": "The filter to apply to the list of operations." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "operations": { "type": "array", "items": { "$ref": "#/components/schemas/operationSchema" }, "description": "The operations." }, "nextPageToken": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The next page token." } }, "required": [ "operations", "nextPageToken" ], "definitions": { "operationSchema": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^operations\\/[a-zA-Z0-9---_]{1,50}$", "description": "The id of the operation, in the format `operations/`." }, "type": { "type": "string", "enum": [ "plan_optimization" ] }, "done": { "type": "boolean", "description": "Whether the operation is done." }, "metadata": { "type": "object", "properties": { "canceled": { "type": "boolean", "description": "Whether the operation was canceled." }, "startedAt": { "type": "number", "description": "The time the operation started at, in seconds since epoch." }, "finishedAt": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "The time the operation finished at, in seconds since epoch." }, "startedBy": { "anyOf": [ { "type": "string", "enum": [ "dispatcher" ] }, { "type": "string", "enum": [ "api" ] }, { "type": "string" } ], "description": "The entity that started the operation." }, "targetPlanId": { "type": "string", "pattern": "^plans\\/[a-zA-Z0-9---_]{1,50}$", "description": "The id of the plan, in the format `plans/`." } }, "required": [ "canceled", "startedAt", "finishedAt", "startedBy", "targetPlanId" ], "description": "Metadata related to a plan optimization operation." }, "result": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "numOptimizedStops": { "type": "number", "description": "The number of stops that were considered for optimization." }, "skippedStops": { "type": "array", "items": { "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/`." }, "reason": { "anyOf": [ { "type": "string", "enum": [ "impossible_time_window" ] }, { "type": "string", "enum": [ "impossible_navigation" ] }, { "type": "string", "enum": [ "impossible_number_of_stops" ] }, { "type": "string", "enum": [ "impossible_order_of_stops" ] }, { "type": "string" } ], "description": "The reason the stop was skipped." } }, "required": [ "id", "reason" ] }, "description": "The stops that were skipped, if any." } }, "required": [ "numOptimizedStops", "skippedStops" ] }, { "type": "object", "properties": { "code": { "type": "string", "description": "A code that identifies the error" }, "message": { "type": "string", "description": "A human-readable message that describes the error. This message is not intended to be parsed by machines." } }, "required": [ "code", "message" ] } ] }, { "type": "null" } ], "description": "The result of the plan optimization operation, or an error." } }, "required": [ "id", "type", "done", "metadata", "result" ] } }, "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" } } } }, "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" } } } } } } }, "/unassignedStops/{unassignedStopId}": { "get": { "operationId": "getUnassignedStop", "summary": "Retrieve an unassigned stop", "tags": [ "Unassigned Stops" ], "description": "Retrieve an unassigned stop", "parameters": [ { "schema": { "type": "string", "pattern": "^[a-zA-Z0-9---_]{1,50}$" }, "in": "path", "name": "unassignedStopId", "required": true, "description": "The unassigned stop id" } ], "responses": { "200": { "description": "The requested unassigned stop", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/unassignedStopSchema", "description": "The requested unassigned 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" } } } }, "404": { "description": "The provided unassigned stop id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "enum": [ "Unassigned stop not found" ] } }, "required": [ "message" ], "description": "The provided unassigned stop id does not exist" } } } }, "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": "deleteUnassignedStop", "summary": "Delete an unassigned stop", "tags": [ "Unassigned Stops" ], "description": "Delete an unassigned stop. This action cannot be undone and will delete all the data associated with the unassigned stop.", "parameters": [ { "schema": { "type": "string", "pattern": "^[a-zA-Z0-9---_]{1,50}$" }, "in": "path", "name": "unassignedStopId", "required": true, "description": "The unassigned stop id" } ], "responses": { "204": { "description": "Unassigned 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" } } } }, "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" } } } } } }, "patch": { "operationId": "updateUnassignedStop", "summary": "Update an existing unassigned stop", "tags": [ "Unassigned Stops" ], "description": "Does not support updating a unassigned stop's location, nor the `clientId`. To do so, delete the unassignedStop and create a new one.", "requestBody": { "content": { "application/json": { "schema": { "description": "The request body for updating an unassigned stop. All the values present in the request will update the unassigned stop value. If you wish to update only certain fields, only set those and do not set the others. Any fields not set will not be updated.", "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", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "currency": { "description": "Currency of the payment. Defaults to the team's currency.", "anyOf": [ { "type": "string", "enum": [ "AED", "ARS", "AUD", "BRL", "CAD", "CHF", "CLP", "CNY", "COP", "DKK", "EGP", "EUR", "GBP", "HKD", "HUF", "ILS", "INR", "JPY", "KRW", "MYR", "MXN", "NOK", "NZD", "PEN", "RON", "RUB", "SAR", "SEK", "SGD", "TRY", "USD", "UYU", "ZAR" ] }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "proofOfAttemptRequirements": { "anyOf": [ { "description": "Proof of attempt requirement settings for this stop", "type": "object", "properties": { "enabled": { "description": "Whether proof of attempt is required for this stop", "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "allowedDrivers": { "description": "Driver IDs that are allowed to be assigned to this stop. If not provided, the stop will be assigned to any available driver during optimization.", "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": 50, "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" } ] }, "depot": { "description": "The Depot ID that this unassigned stop belongs to, in the format `depot/`. If null, it will default to the team's main depot. If not provided, it will not be updated.", "anyOf": [ { "type": "string", "pattern": "^depots\\/[a-zA-Z0-9---_]{1,50}$" }, { "type": "null" } ] } }, "additionalProperties": false } } }, "description": "The request body for updating an unassigned stop. All the values present in the request will update the unassigned stop value. If you wish to update only certain fields, only set those and do not set the others. Any fields not set will not be updated." }, "parameters": [ { "schema": { "type": "string", "pattern": "^[a-zA-Z0-9---_]{1,50}$" }, "in": "path", "name": "unassignedStopId", "required": true, "description": "The unassigned stop id" } ], "responses": { "200": { "description": "The updated unassigned stop", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/unassignedStopSchema", "description": "The updated unassigned 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 request contains fields that are not supported by your team subscription/settings.", "content": { "application/json": { "schema": { "oneOf": [ { "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 request contains fields that are not supported by 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" } } } }, "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" } } } } } } }, "/unassignedStops": { "get": { "operationId": "listUnassignedStops", "summary": "List unassigned stops", "tags": [ "Unassigned Stops" ], "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "in": "query", "name": "pageToken", "required": false, "description": "The page token to continue from." }, { "schema": { "default": 20, "type": "number", "minimum": 1, "maximum": 20 }, "in": "query", "name": "maxPageSize", "required": false, "description": "The maximum number of unassigned stops to return per page." }, { "schema": { "type": "object", "properties": { "externalId": { "description": "Filter by the `recipient.externalId` field, exact match", "type": "string", "minLength": 1, "maxLength": 255 } } }, "in": "query", "name": "filter", "required": false, "description": "The filter to apply to the list of unassigned stops." } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "unassignedStops": { "type": "array", "items": { "$ref": "#/components/schemas/unassignedStopSchema" }, "description": "The unassignedStops." }, "nextPageToken": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The next page token." } }, "required": [ "unassignedStops", "nextPageToken" ], "definitions": { "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." }, "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." }, "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": 1, "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." } }, "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" } } } }, "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" } } } } } }, "post": { "operationId": "createUnassignedStop", "summary": "Create a new unassigned stop", "tags": [ "Unassigned Stops" ], "description": "Create a new unassigned stop with the given data.", "requestBody": { "content": { "application/json": { "schema": { "description": "The request body for creating an unassigned stop. Address is a required field, you need to provide at least one of the fields in it. The latitude and longitude fields will override any of the other fields if they are set (and they need to be both set if any of them are). The more fields you provide the more accurate the geocoding will be. The depotId field is not required, but will default to the main depot of the team if not provided, be sure to provide it if you want to use a different depot.", "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 }, "depot": { "description": "The Depot ID that this unassigned stop belongs to, in the format `depot/`. If not provided, or null, it will default to the team's main depot.", "anyOf": [ { "type": "string", "pattern": "^depots\\/[a-zA-Z0-9---_]{1,50}$" }, { "type": "null" } ] }, "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", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "currency": { "description": "Currency of the payment. Defaults to the team's currency.", "anyOf": [ { "type": "string", "enum": [ "AED", "ARS", "AUD", "BRL", "CAD", "CHF", "CLP", "CNY", "COP", "DKK", "EGP", "EUR", "GBP", "HKD", "HUF", "ILS", "INR", "JPY", "KRW", "MYR", "MXN", "NOK", "NZD", "PEN", "RON", "RUB", "SAR", "SEK", "SGD", "TRY", "USD", "UYU", "ZAR" ] }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "proofOfAttemptRequirements": { "anyOf": [ { "description": "Proof of attempt requirement settings for this stop", "type": "object", "properties": { "enabled": { "description": "Whether proof of attempt is required for this stop", "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "allowedDrivers": { "description": "Driver IDs that are allowed to be assigned to this stop. If not provided, the stop will be assigned to any available driver during optimization.", "anyOf": [ { "maxItems": 100, "type": "array", "items": { "type": "string", "pattern": "^drivers\\/[a-zA-Z0-9---_]{1,50}$" } }, { "type": "null" } ] }, "activity": { "description": "Activity type", "default": "delivery", "anyOf": [ { "type": "string", "enum": [ "delivery", "pickup" ] }, { "type": "null" } ] }, "optimizationOrder": { "description": "The preferred order of this stop in the optimized route. If not provided or `\"default\"`, the stop will be placed in the optimal order, decided by the optimization algorithm. Otherwise it will be placed either `\"first\"` or `\"last\"`.", "anyOf": [ { "type": "string", "enum": [ "first", "last", "default" ] }, { "type": "null" } ] }, "packageCount": { "description": "Number of packages in the stop", "anyOf": [ { "type": "number", "minimum": 1, "maximum": 10000 }, { "type": "null" } ] }, "weight": { "description": "Weight information for this stop.", "anyOf": [ { "type": "object", "properties": { "amount": { "description": "The weight amount for this stop.", "type": "number", "minimum": 0, "maximum": 999999, "multipleOf": 0.01 }, "unit": { "description": "The weight unit in which the amount is specified.", "type": "string", "enum": [ "kilogram", "pound", "metric-ton" ] } }, "required": [ "amount", "unit" ] }, { "type": "null" } ] }, "notes": { "description": "Notes for the stop", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] }, "clientId": { "description": "Client ID of the retailer in Spoke Connect", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "barcodes": { "description": "List of barcode IDs associated with this stop", "maxItems": 50, "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, "description": "The request body for creating an unassigned stop. Address is a required field, you need to provide at least one of the fields in it. The latitude and longitude fields will override any of the other fields if they are set (and they need to be both set if any of them are). The more fields you provide the more accurate the geocoding will be. The depotId field is not required, but will default to the main depot of the team if not provided, be sure to provide it if you want to use a different depot." }, "responses": { "200": { "description": "The created unassignedStop", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/unassignedStopSchema", "description": "The created unassignedStop" } } } }, "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 request contains fields that are not supported by your team subscription/settings.", "content": { "application/json": { "schema": { "oneOf": [ { "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 request contains fields that are not supported by your team subscription/settings." } } } }, "404": { "description": "The provided driver id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "anyOf": [ { "type": "string", "enum": [ "Driver not found" ] }, { "type": "string" } ] } }, "required": [ "message" ], "description": "The provided driver id does not exist", "title": "Driver not found" } } } }, "422": { "description": "Failed to create stop", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "anyOf": [ { "type": "string", "enum": [ "An error occurred when creating the unassigned 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" } } } } } } }, "/unassignedStops:import": { "post": { "operationId": "importUnassignedStops", "summary": "Batch import unassigned stops", "tags": [ "Unassigned Stops" ], "description": "Batch import unassigned stops. The request body must contain an array of unassigned stops to import. Note that the `depot` is the same for all unassigned stops in a same request. This is because the depot is used as a biasing location for the unassigned stops, so that the geocoding results are more accurate for a same region.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "unassignedStops": { "description": "An array of unassigned stops to import in batch. Supports a maximum of 100 unassigned stops per request. Note that the `depot` is shared across all unassigned stops in the request, and thus should not be provided for individual unassigned stops. That is because the `depot` location is used to bias the geocoding results of the stops.", "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", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "currency": { "description": "Currency of the payment. Defaults to the team's currency.", "anyOf": [ { "type": "string", "enum": [ "AED", "ARS", "AUD", "BRL", "CAD", "CHF", "CLP", "CNY", "COP", "DKK", "EGP", "EUR", "GBP", "HKD", "HUF", "ILS", "INR", "JPY", "KRW", "MYR", "MXN", "NOK", "NZD", "PEN", "RON", "RUB", "SAR", "SEK", "SGD", "TRY", "USD", "UYU", "ZAR" ] }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "proofOfAttemptRequirements": { "anyOf": [ { "description": "Proof of attempt requirement settings for this stop", "type": "object", "properties": { "enabled": { "description": "Whether proof of attempt is required for this stop", "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "additionalProperties": false }, { "type": "null" } ] }, "allowedDrivers": { "description": "Driver IDs that are allowed to be assigned to this stop. If not provided, the stop will be assigned to any available driver during optimization.", "anyOf": [ { "maxItems": 100, "type": "array", "items": { "type": "string", "pattern": "^drivers\\/[a-zA-Z0-9---_]{1,50}$" } }, { "type": "null" } ] }, "activity": { "description": "Activity type", "default": "delivery", "anyOf": [ { "type": "string", "enum": [ "delivery", "pickup" ] }, { "type": "null" } ] }, "optimizationOrder": { "description": "The preferred order of this stop in the optimized route. If not provided or `\"default\"`, the stop will be placed in the optimal order, decided by the optimization algorithm. Otherwise it will be placed either `\"first\"` or `\"last\"`.", "anyOf": [ { "type": "string", "enum": [ "first", "last", "default" ] }, { "type": "null" } ] }, "packageCount": { "description": "Number of packages in the stop", "anyOf": [ { "type": "number", "minimum": 1, "maximum": 10000 }, { "type": "null" } ] }, "weight": { "description": "Weight information for this stop.", "anyOf": [ { "type": "object", "properties": { "amount": { "description": "The weight amount for this stop.", "type": "number", "minimum": 0, "maximum": 999999, "multipleOf": 0.01 }, "unit": { "description": "The weight unit in which the amount is specified.", "type": "string", "enum": [ "kilogram", "pound", "metric-ton" ] } }, "required": [ "amount", "unit" ] }, { "type": "null" } ] }, "notes": { "description": "Notes for the stop", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] }, "clientId": { "description": "Client ID of the retailer in Spoke Connect", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "barcodes": { "description": "List of barcode IDs associated with this stop", "maxItems": 50, "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 } }, "depot": { "description": "The Depot ID the unassigned stops in the batch belong to, in the format `depot/`. This is used to bias the geocoding results of the unassigned stops, so every unassigned stop in the batch should belong to the same depot. If not provided, or null, it will default to the team's main depot.", "anyOf": [ { "type": "string", "pattern": "^depots\\/[a-zA-Z0-9---_]{1,50}$" }, { "type": "null" } ] } }, "required": [ "unassignedStops" ], "additionalProperties": false } } }, "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "array", "items": { "type": "string", "pattern": "^unassignedStops\\/[a-zA-Z0-9---_]{1,50}$", "description": "The id of the unassigned stop, in the format `unassignedStops/`." }, "description": "The ids of the successfully imported unassigned stops" }, "failed": { "type": "array", "items": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "description": "The error that occurred during import" } }, "required": [ "message" ] }, "unassignedStop": { "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 unassigned 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 unassigned stop that failed to import" } }, "required": [ "address", "recipient" ], "description": "The unassigned stop that failed to import" } }, "required": [ "error", "unassignedStop" ] }, "description": "The failed unassigned 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 request contains fields that are not supported by your team subscription/settings.", "content": { "application/json": { "schema": { "oneOf": [ { "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 request contains fields that are not supported by your team subscription/settings." } } } }, "404": { "description": "A depot or a driver was not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." } }, "required": [ "message" ], "description": "A depot or a driver was not found" } } } }, "422": { "description": "Failed to create stop", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "anyOf": [ { "type": "string", "enum": [ "An error occurred when creating the unassigned 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" } } } } } } }, "/team/customStopProperties": { "get": { "operationId": "listCustomStopProperties", "summary": "List custom stop properties", "tags": [ "Team" ], "description": "Returns a list of custom stop properties definitions.", "responses": { "200": { "description": "The set of custom stop properties.", "content": { "application/json": { "schema": { "type": "object", "properties": { "customStopProperties": { "type": "array", "items": { "$ref": "#/components/schemas/customStopPropertySchema" }, "description": "The set of custom stop properties." } }, "required": [ "customStopProperties" ], "definitions": { "customStopPropertySchema": { "type": "object", "properties": { "id": { "type": "string", "description": "The custom stop property id" }, "name": { "type": "string", "description": "The name of the custom stop property" }, "visibleToDrivers": { "type": "boolean", "description": "Whether this custom stop property is visible to drivers." }, "visibleToRecipients": { "type": "boolean", "description": "Whether this property is visible to recipients." } }, "required": [ "id", "name", "visibleToDrivers", "visibleToRecipients" ], "additionalProperties": false, "description": "The definition of a custom stop property." } }, "description": "The set of custom stop properties." } } } }, "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": "Feature not included in your team subscription", "content": { "application/json": { "schema": { "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" } } } }, "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" } } } } } } }, "/team/customStopProperties/{customStopPropertyId}": { "get": { "operationId": "getCustomStopProperty", "summary": "Retrieve a custom stop property", "tags": [ "Team" ], "description": "Returns a custom stop property definition.", "parameters": [ { "schema": { "type": "string", "maxLength": 50 }, "in": "path", "name": "customStopPropertyId", "required": true, "description": "The custom stop property id" } ], "responses": { "200": { "description": "The definition of a custom stop property.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "The custom stop property id" }, "name": { "type": "string", "description": "The name of the custom stop property" }, "visibleToDrivers": { "type": "boolean", "description": "Whether this custom stop property is visible to drivers." }, "visibleToRecipients": { "type": "boolean", "description": "Whether this property is visible to recipients." } }, "required": [ "id", "name", "visibleToDrivers", "visibleToRecipients" ], "additionalProperties": false, "description": "The definition of a custom stop property." } } } }, "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": "Feature not included in your team subscription", "content": { "application/json": { "schema": { "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" } } } }, "404": { "description": "The provided custom stop property id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "anyOf": [ { "type": "string", "enum": [ "Custom stop property not found" ] }, { "type": "string" } ] } }, "required": [ "message" ], "description": "The provided custom stop property id does not exist", "title": "Custom stop property 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" } } } } } } }, "/members": { "post": { "operationId": "createMember", "summary": "Create a new member", "tags": [ "Members" ], "description": "Create a member with the given data in your team. Prefer using the [batch import endpoint](#operation/importMembers) for creating multiple members at once as it is more efficient.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "The member's full name", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "displayName": { "description": "The name displayed for the member in the UI", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "email": { "description": "Member's email", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "linkedDriverId": { "description": "The existing driver to link the member to", "anyOf": [ { "type": "string", "pattern": "^drivers\\/[a-zA-Z0-9---_]{1,50}$" }, { "type": "null" } ] }, "role": { "description": "The operational role given to the member.", "type": "string", "enum": [ "admin", "depot-manager", "dispatcher", "read-only" ] }, "depots": { "description": "The depot IDs associated with the member in the format `depots/`, duplicates will be ignored. If set to null or not provided, the team's Main depot will be set as member depot.", "anyOf": [ { "minItems": 1, "maxItems": 50, "type": "array", "items": { "description": "The depot ID, in the format `depots/`", "type": "string", "pattern": "^depots\\/[a-zA-Z0-9---_]{1,50}$" } }, { "type": "null" } ] } }, "required": [ "role" ], "additionalProperties": false } } }, "required": true }, "responses": { "200": { "description": "The created member", "content": { "application/json": { "schema": { "description": "The created member", "$ref": "#/components/schemas/memberSchema" } } } }, "400": { "description": "Failed to validate the request", "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": "Failed to validate the request" } } } }, "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" } } } }, "404": { "description": "The linked driver could not be found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "anyOf": [ { "type": "string", "enum": [ "Driver not found" ] }, { "type": "string" } ] } }, "required": [ "message" ], "description": "The linked driver could not be found.", "title": "Driver not found" } } } }, "409": { "description": "Conflict when creating member.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "anyOf": [ { "type": "string", "enum": [ "The member could not be created because of a conflict, such as a member already existing with the same email." ] }, { "type": "string" } ] } }, "required": [ "message" ], "description": "Conflict when creating member." } } } }, "422": { "description": "Failed to create member.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "anyOf": [ { "type": "string", "enum": [ "An error occured when creating the member, 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 member." } } } }, "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" } } } } } } }, "/members/{memberId}": { "patch": { "operationId": "updateMember", "summary": "Update a member", "tags": [ "Members" ], "description": "Updates a member from your team.", "requestBody": { "content": { "application/json": { "schema": { "description": "The request body for updating a member.", "type": "object", "properties": { "name": { "description": "The member's full name", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "displayName": { "description": "The name displayed for the member in the UI", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "role": { "description": "The operational role given to the member.", "anyOf": [ { "description": "The operational role given to the member.", "type": "string", "enum": [ "admin", "depot-manager", "dispatcher", "read-only" ] }, { "type": "null" } ] }, "depots": { "description": "The depot IDs associated with the member in the format `depots/`, duplicates will be ignored. If set to null or not provided, the team's Main depot will be set as member depot.", "anyOf": [ { "minItems": 1, "maxItems": 50, "type": "array", "items": { "description": "The depot ID, in the format `depots/`", "type": "string", "pattern": "^depots\\/[a-zA-Z0-9---_]{1,50}$" } }, { "type": "null" } ] } }, "additionalProperties": false } } }, "description": "The request body for updating a member." }, "parameters": [ { "schema": { "type": "string", "pattern": "^[a-zA-Z0-9---_]{1,50}$" }, "in": "path", "name": "memberId", "required": true, "description": "The member id" } ], "responses": { "200": { "description": "The updated member", "content": { "application/json": { "schema": { "description": "The updated member", "$ref": "#/components/schemas/memberSchema" } } } }, "400": { "description": "Failed to validate the request", "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": "Failed to validate the request" } } } }, "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" } } } }, "404": { "description": "The provided member id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "anyOf": [ { "type": "string", "enum": [ "Member not found" ] }, { "type": "string" } ] } }, "required": [ "message" ], "description": "The provided member id does not exist", "title": "Member not found" } } } }, "422": { "description": "Failed to update member.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "anyOf": [ { "type": "string", "enum": [ "An error occured when updating the member, 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 update member." } } } }, "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": "deleteMember", "summary": "Remove a member", "tags": [ "Members" ], "description": "Removes a member from your team. If the member also has driver access, the member will only have their operational role(s) revoked; thus not being listed among the team members, but will keep their driver access.", "parameters": [ { "schema": { "type": "string", "pattern": "^[a-zA-Z0-9---_]{1,50}$" }, "in": "path", "name": "memberId", "required": true, "description": "The member id" } ], "responses": { "204": { "description": "Member removed 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" } } } }, "404": { "description": "The provided member id does not exist", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "anyOf": [ { "type": "string", "enum": [ "Member not found" ] }, { "type": "string" } ] } }, "required": [ "message" ], "description": "The provided member id does not exist", "title": "Member not found" } } } }, "422": { "description": "Failed to delete member.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "The error message." } }, "required": [ "message" ], "description": "Failed to delete member." } } } }, "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" } } } } } } }, "/members:import": { "post": { "operationId": "importMembers", "summary": "Import multiple members", "tags": [ "Members" ], "description": "Import multiple members at once.", "requestBody": { "content": { "application/json": { "schema": { "description": "An array of member descriptions to be created in batch.", "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "name": { "description": "The member's full name", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "displayName": { "description": "The name displayed for the member in the UI", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "email": { "description": "Member's email", "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "linkedDriverId": { "description": "The existing driver to link the member to", "anyOf": [ { "type": "string", "pattern": "^drivers\\/[a-zA-Z0-9---_]{1,50}$" }, { "type": "null" } ] }, "role": { "description": "The operational role given to the member.", "type": "string", "enum": [ "admin", "depot-manager", "dispatcher", "read-only" ] }, "depots": { "description": "The depot IDs associated with the member in the format `depots/`, duplicates will be ignored. If set to null or not provided, the team's Main depot will be set as member depot.", "anyOf": [ { "minItems": 1, "maxItems": 50, "type": "array", "items": { "description": "The depot ID, in the format `depots/`", "type": "string", "pattern": "^depots\\/[a-zA-Z0-9---_]{1,50}$" } }, { "type": "null" } ] } }, "required": [ "role" ], "additionalProperties": false } } } }, "description": "An array of member descriptions to be created in batch." }, "responses": { "200": { "description": "The imported members", "content": { "application/json": { "schema": { "description": "The imported members", "type": "object", "properties": { "success": { "type": "array", "items": { "type": "string", "pattern": "^members\\/[a-zA-Z0-9---_]{1,50}$", "description": "The id of the member, in the format `members/`." }, "description": "The ids of the successfully imported members" }, "failed": { "type": "array", "items": { "type": "object", "properties": { "error": { "type": "object", "properties": { "message": { "type": "string", "description": "The error that occurred during import" } }, "required": [ "message" ] }, "member": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "The member's full name" }, "displayName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ], "description": "The name displayed for the member in the UI" }, "email": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ], "description": "Member's email" }, "linkedDriverId": { "anyOf": [ { "type": "string", "pattern": "^drivers\\/[a-zA-Z0-9---_]{1,50}$" }, { "type": "null" } ], "description": "The existing driver to link the member to" }, "role": { "type": "string", "enum": [ "admin", "depot-manager", "dispatcher", "read-only" ], "description": "The operational role given to the member." }, "depots": { "anyOf": [ { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "string", "pattern": "^depots\\/[a-zA-Z0-9---_]{1,50}$", "description": "The depot ID, in the format `depots/`" } }, { "type": "null" } ], "description": "The depot IDs associated with the member in the format `depots/`, duplicates will be ignored. If set to null or not provided, the team's Main depot will be set as member depot." } }, "required": [ "role" ], "description": "The request body for creating a member." } }, "required": [ "error", "member" ] }, "description": "The failed members" } }, "required": [ "success", "failed" ] } } } }, "400": { "description": "Failed to validate the request", "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": "Failed to validate the request" } } } }, "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" } } } }, "409": { "description": "Conflict when creating member.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "anyOf": [ { "type": "string", "enum": [ "The member could not be created because of a conflict, such as a member already existing with the same email." ] }, { "type": "string" } ] } }, "required": [ "message" ], "description": "Conflict when creating member." } } } }, "422": { "description": "Failed to import members.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "anyOf": [ { "type": "string", "enum": [ "An error occured when importing members, 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 import members." } } } }, "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.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" } ], "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." }, "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." }, "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": 1, "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" } }, "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" ], "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." }, "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." }, "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": 1, "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" } } } } } } } }, "servers": [ { "url": "https://api.spoke.com/public/v1" } ], "security": [ { "BasicAuth": [] } ], "tags": [ { "name": "Plans", "description": "Endpoints to operate on [Plans](/docs/models/plan) resources.\n" }, { "name": "Stops", "description": "Endpoints to operate on [Stop](/docs/models/stop) resources.\n\nFor any [Plans](/docs/models/plan) created before 2023-04-01 the stop\ncollections and all related operations will not be available.\n\nFor any operations here you will need a Plan ID beforehand. You can retrieve an\nexisting Plan by [listing your Plans](#tag/Plans/operation/listPlans) or you can\n[create a new one](#tag/Plans/operation/createPlan).\n" }, { "name": "Unassigned Stops", "description": "Endpoints to operate on [Unassigned Stop](/docs/models/unassignedStop) resources.\n" }, { "name": "Live Plans", "description": "Endpoints to operate on [Plans](/docs/models/plan) resources when it's pending re-optimization and re-distribution.\n\nYou must use these endpoints to apply the changes when any [Live Stops](#tag/Live-Stops) request returns `pending = true`.\n" }, { "name": "Live Stops", "description": "Endpoints to operate on [Stop](/docs/models/stop) resources when the plan is already optimized and therefore not writable.\n\nAll the endpoints return the field `pending`. This field indicates whether the\nchange has been applied to the plan or if it's pending a new optimization and distribution. On `pending = true`,\nyou must use the [re-optimize](#tag/Live-Plans/operation/reoptimizePlan) and [re-distribute](#tag/Live-Plans/operation/redistributePlan)\nendpoints to apply the changes to the plan.\n" }, { "name": "Drivers", "description": "Endpoints to operate on [Drivers](/docs/models/driver) resources.\n" }, { "name": "Depots", "description": "Endpoints to operate on [Depots](/docs/models/depot) resources.\n\nThis resource is currently read-only on the API.\n" }, { "name": "Routes", "description": "Endpoints to operate on [Routes](/docs/models/route) resources.\n\nThis resource is currently read-only on the API.\n" }, { "name": "Operations", "description": "Endpoints to operate on [Operations](/docs/models/operation) resources.\n" }, { "name": "Team", "description": "Endpoints to retrieve [Custom Stop Properties](/docs/models/customStopProperty).\n" }, { "name": "Members", "description": "Endpoints to operate on Members resources.\n" } ] }