Interactive example · API v1
Build a delivery plan with the API
Create a driver first. We’ll carry forward all required IDs into each request.
Simulated · No API key · No real invitations
Enable JavaScript to try this interactive simulation.
How the requests connect
Driver and plan IDs
The returned driver ID assigns the plan. The plan ID connects the stops and later requests.
Optimization status
The operation ID tracks optimization until it succeeds. The resulting plan can then be reviewed.
Separate distribution
After review, a separate request marks the simulated plan as distributed.
Limits of this simulation
This runs with fictional data and makes no changes to a Spoke account. It does not invite drivers, geocode addresses, send notifications or distribute a real plan. Responses and timing are illustrative; live account and scheduling rules may differ.
This workflow is built from OpenAPI’s Arazzo format
Arazzo is a format from the OpenAPI Initiative for describing API workflows: which requests to make, how data passes between them, and what counts as success. It works alongside OpenAPI, which describes the individual operations and their request and response schemas.
Learn more about Arazzo. This example uses Arazzo 1.0.1, with extensions for its presentation and example inputs.
View Arazzo document
The exact definition used by this example.
{
"arazzo": "1.0.1",
"info": {
"title": "Build a delivery plan with the API",
"version": "0.1.0",
"description": "Turn delivery addresses into an optimized plan, ready for your driver. Explore the connected API v1 requests with fictional data."
},
"sourceDescriptions": [
{
"name": "dispatch",
"url": "https://developer.dispatch.spoke.com/openapi-v1.json",
"type": "openapi"
}
],
"workflows": [
{
"workflowId": "dispatchPlanGoldenPath",
"summary": "Create delivery work and distribute an optimized plan to its driver",
"inputs": {
"type": "object",
"properties": {
"driver": {
"$ref": "https://developer.dispatch.spoke.com/openapi-v1.json#/paths/~1drivers/post/requestBody/content/application~1json/schema"
},
"stop": {
"$ref": "https://developer.dispatch.spoke.com/openapi-v1.json#/paths/~1plans~1{planId}~1stops/post/requestBody/content/application~1json/schema"
},
"planTitle": {
"$ref": "https://developer.dispatch.spoke.com/openapi-v1.json#/paths/~1plans/post/requestBody/content/application~1json/schema/properties/title"
},
"planDate": {
"$ref": "https://developer.dispatch.spoke.com/openapi-v1.json#/paths/~1plans/post/requestBody/content/application~1json/schema/properties/starts"
},
"routeStart": {
"$ref": "https://developer.dispatch.spoke.com/openapi-v1.json#/paths/~1plans/post/requestBody/content/application~1json/schema/properties/routeOverrides/anyOf/0/properties/startAddress"
},
"routeEnd": {
"$ref": "https://developer.dispatch.spoke.com/openapi-v1.json#/paths/~1plans/post/requestBody/content/application~1json/schema/properties/routeOverrides/anyOf/0/properties/endAddress"
}
},
"required": [
"driver",
"planTitle",
"planDate",
"routeStart",
"routeEnd",
"stop"
],
"examples": [
{
"driver": {
"name": "Alex Example",
"email": "alex@example.com"
},
"stop": {
"address": {
"addressLineOne": "10 Example Street",
"city": "London",
"country": "GB"
}
},
"planTitle": "Example delivery plan",
"planDate": {
"day": 4,
"month": 9,
"year": 2026
},
"routeStart": {
"addressLineOne": "1 Example Depot Road",
"city": "London",
"country": "GB"
},
"routeEnd": {
"addressLineOne": "1 Example Depot Road",
"city": "London",
"country": "GB"
}
}
]
},
"steps": [
{
"stepId": "createDriver",
"operationId": "createDriver",
"description": "Create a driver to assign to the delivery plan.",
"x-spoke-demo": {
"title": "Create a driver",
"successMessage": "Driver created. You can now assign this driver to a plan.",
"outputLabels": {
"driverId": "Driver ID"
},
"explanation": "Send the driver's name and email. The response returns a full `drivers/<id>` resource ID, which the plan request uses to assign this driver.",
"fields": [
{
"name": "name",
"path": "/name",
"label": "Driver name",
"hideDescription": true,
"required": true,
"inputPath": "/driver/name"
},
{
"name": "email",
"path": "/email",
"label": "Driver email",
"hideDescription": true,
"required": true,
"inputPath": "/driver/email"
}
],
"exampleInputs": {
"name": "Alex Example",
"email": "alex@example.com"
}
},
"requestBody": {
"contentType": "application/json",
"payload": "$inputs.driver"
},
"successCriteria": [
{
"condition": "$statusCode == 200"
}
],
"outputs": {
"driverId": "$response.body#/id"
}
},
{
"stepId": "createPlan",
"operationId": "createPlan",
"description": "Set the delivery date and route start and end locations for your driver.",
"x-spoke-demo": {
"title": "Create a plan",
"successMessage": "Plan created with your driver assigned.",
"outputLabels": {
"planId": "Plan ID"
},
"explanation": "The request includes the driver's full resource ID from the previous step. Postal addresses are preferable for route start and end locations; latitude and longitude are also accepted and take precedence over address text when provided. The response returns a plan ID used by later requests.",
"fields": [
{
"name": "title",
"path": "/title",
"label": "Plan title",
"hideDescription": true,
"required": true,
"inputPath": "/planTitle"
},
{
"name": "date",
"path": "/starts",
"label": "Plan date",
"widget": "date-parts",
"inputPath": "/planDate"
},
{
"name": "startAddressLineOne",
"path": "/routeOverrides/startAddress/addressLineOne",
"label": "Address line 1",
"group": "Start location",
"hideDescription": true,
"required": true,
"inputPath": "/routeStart/addressLineOne"
},
{
"name": "startCity",
"path": "/routeOverrides/startAddress/city",
"label": "City",
"group": "Start location",
"hideDescription": true,
"required": true,
"inputPath": "/routeStart/city"
},
{
"name": "startCountry",
"path": "/routeOverrides/startAddress/country",
"label": "Country",
"group": "Start location",
"hideDescription": true,
"required": true,
"inputPath": "/routeStart/country"
},
{
"name": "endAddressLineOne",
"path": "/routeOverrides/endAddress/addressLineOne",
"label": "Address line 1",
"group": "End location",
"hideDescription": true,
"required": true,
"inputPath": "/routeEnd/addressLineOne"
},
{
"name": "endCity",
"path": "/routeOverrides/endAddress/city",
"label": "City",
"group": "End location",
"hideDescription": true,
"required": true,
"inputPath": "/routeEnd/city"
},
{
"name": "endCountry",
"path": "/routeOverrides/endAddress/country",
"label": "Country",
"group": "End location",
"hideDescription": true,
"required": true,
"inputPath": "/routeEnd/country"
}
],
"exampleInputs": {
"title": "Example delivery plan",
"date": {
"generator": "local-date"
},
"startAddressLineOne": "1 Example Depot Road",
"startCity": "London",
"startCountry": "GB",
"endAddressLineOne": "1 Example Depot Road",
"endCity": "London",
"endCountry": "GB"
}
},
"requestBody": {
"contentType": "application/json",
"payload": {
"title": "",
"starts": {},
"drivers": [
""
],
"routeOverrides": {
"startAddress": {},
"endAddress": {}
}
},
"replacements": [
{
"target": "/title",
"value": "$inputs.planTitle"
},
{
"target": "/starts",
"value": "$inputs.planDate"
},
{
"target": "/drivers/0",
"value": "$steps.createDriver.outputs.driverId"
},
{
"target": "/routeOverrides/startAddress",
"value": "$inputs.routeStart"
},
{
"target": "/routeOverrides/endAddress",
"value": "$inputs.routeEnd"
}
]
},
"successCriteria": [
{
"condition": "$statusCode == 200"
},
{
"condition": "$response.body.writable == true"
},
{
"condition": "$response.body.distributed == false"
},
{
"condition": "$response.body.drivers[0] == $steps.createDriver.outputs.driverId"
}
],
"outputs": {
"planId": "$response.body#/id"
}
},
{
"stepId": "createStop",
"operationId": "createStop",
"description": "Add a delivery stop to the plan. Repeat for more stops.",
"x-spoke-demo": {
"title": "Add delivery stops",
"repeatable": true,
"successMessage": "Stop created in your plan.",
"outputLabels": {
"stopId": "Stop ID"
},
"explanation": "This request uses the plan ID from creation and sends the stop's street address. Dispatch can geocode the address; you can instead supply both latitude and longitude, which take precedence over address text. In this simulation, an address-only response has null coordinates because no geocoding runs. Repeat the request to add more stops before optimization.",
"fields": [
{
"name": "addressLineOne",
"path": "/address/addressLineOne",
"label": "Address line 1",
"hideDescription": true,
"required": true,
"inputPath": "/stop/address/addressLineOne"
},
{
"name": "city",
"hideDescription": true,
"path": "/address/city",
"required": true,
"inputPath": "/stop/address/city"
},
{
"name": "country",
"hideDescription": true,
"path": "/address/country",
"required": true,
"inputPath": "/stop/address/country"
}
],
"exampleInputs": {
"addressLineOne": "10 Example Street",
"city": "London",
"country": "GB"
}
},
"parameters": [
{
"name": "planId",
"in": "path",
"value": "$steps.createPlan.outputs.planId",
"x-spoke-resource-id": "plans"
}
],
"requestBody": {
"contentType": "application/json",
"payload": "$inputs.stop"
},
"successCriteria": [
{
"condition": "$statusCode == 200"
}
],
"outputs": {
"stopId": "$response.body#/id"
}
},
{
"stepId": "optimizePlan",
"operationId": "optimizePlan",
"description": "Start optimizing the plan's delivery stops.",
"x-spoke-demo": {
"title": "Optimize the plan",
"successMessage": "Optimization started. Check its status in the next step.",
"outputLabels": {
"operationId": "Operation ID"
},
"explanation": "This request uses the plan ID to start asynchronous optimization. A successful response returns an operation ID, not a finished route. The next step uses that ID to check the result.",
"fields": [],
"exampleInputs": {}
},
"parameters": [
{
"name": "planId",
"in": "path",
"value": "$steps.createPlan.outputs.planId",
"x-spoke-resource-id": "plans"
}
],
"successCriteria": [
{
"condition": "$statusCode == 200"
},
{
"condition": "$response.body.type == 'plan_optimization'"
},
{
"condition": "$response.body.metadata.targetPlanId == $steps.createPlan.outputs.planId"
}
],
"outputs": {
"operationId": "$response.body#/id"
}
},
{
"stepId": "waitForOptimization",
"operationId": "getOperation",
"description": "Check whether optimization has finished before reviewing the plan.",
"x-spoke-demo": {
"title": "Check for optimization",
"manualRetry": true,
"pendingMessage": "Optimization is still running. In a live integration, wait about five seconds between checks to avoid rate limits. This simulation lets you check again now.",
"successMessage": "Optimization complete: delivery stops considered, none skipped.",
"outputLabels": {
"result": "Optimization result"
},
"explanation": "The optimization request returns an operation ID. This step uses it to fetch the operation status. Each click makes one status request; the demo does not check automatically. While pending, `\"done\"` is `false` and `\"result\"` is `null`, so you stay on this step. Once finished, `\"result\"` may contain optimization details or an error. The workflow advances only when the operation succeeds, at least one stop was optimized, and none were skipped.",
"fields": [],
"exampleInputs": {}
},
"parameters": [
{
"name": "operationId",
"in": "path",
"value": "$steps.optimizePlan.outputs.operationId",
"x-spoke-resource-id": "operations"
}
],
"successCriteria": [
{
"condition": "$statusCode == 200"
},
{
"condition": "$response.body.id == $steps.optimizePlan.outputs.operationId"
},
{
"condition": "$response.body.type == 'plan_optimization'"
},
{
"condition": "$response.body.metadata.targetPlanId == $steps.createPlan.outputs.planId"
},
{
"condition": "$response.body.done == true"
},
{
"condition": "$response.body.metadata.canceled == false"
},
{
"condition": "$response.body.result.code == null"
},
{
"condition": "$response.body.result.numOptimizedStops > 0"
},
{
"condition": "$response.body.result.skippedStops.length == 0"
}
],
"onFailure": [
{
"name": "pollPendingOperation",
"type": "retry",
"retryAfter": 0,
"retryLimit": 4,
"criteria": [
{
"condition": "$statusCode == 200"
},
{
"condition": "$response.body.id == $steps.optimizePlan.outputs.operationId"
},
{
"condition": "$response.body.metadata.targetPlanId == $steps.createPlan.outputs.planId"
},
{
"condition": "$response.body.done == false"
},
{
"condition": "$response.body.metadata.canceled == false"
},
{
"condition": "$response.body.result == null"
}
]
},
{
"name": "stopOutsideGoldenPath",
"type": "end"
}
],
"outputs": {
"result": "$response.body#/result"
}
},
{
"stepId": "reviewPlan",
"operationId": "getPlan",
"description": "Check the optimized routes before distribution.",
"x-spoke-demo": {
"title": "Review the optimized plan",
"successMessage": "Optimized plan retrieved with your driver assigned and routes ready for distribution.",
"outputLabels": {
"routeIds": "Route IDs"
},
"explanation": "This request fetches the original plan using its plan ID. The response confirms that it is optimized, still assigned to your driver, and has at least one route. It also returns the route IDs.",
"fields": [],
"exampleInputs": {}
},
"parameters": [
{
"name": "planId",
"in": "path",
"value": "$steps.createPlan.outputs.planId",
"x-spoke-resource-id": "plans"
}
],
"successCriteria": [
{
"condition": "$statusCode == 200"
},
{
"condition": "$response.body.id == $steps.createPlan.outputs.planId"
},
{
"condition": "$response.body.optimization == 'optimized'"
},
{
"condition": "$response.body.distributed == false"
},
{
"condition": "$response.body.drivers[0] == $steps.createDriver.outputs.driverId"
},
{
"condition": "$response.body.routes.length > 0"
}
],
"outputs": {
"routeIds": "$response.body#/routes"
}
},
{
"stepId": "distributePlan",
"operationId": "distributePlan",
"description": "Send the reviewed plan to the driver.",
"x-spoke-demo": {
"title": "Distribute the plan",
"manualOnly": true,
"successMessage": "Plan distributed to its assigned driver in the simulation.",
"outputLabels": {
"planId": "Plan ID",
"distributed": "Distributed",
"routeIds": "Route IDs"
},
"explanation": "This separate request uses the plan ID from creation to distribute the plan. A successful response returns the same plan with `distributed: true` and its route IDs.",
"fields": [],
"exampleInputs": {}
},
"parameters": [
{
"name": "planId",
"in": "path",
"value": "$steps.createPlan.outputs.planId",
"x-spoke-resource-id": "plans"
}
],
"successCriteria": [
{
"condition": "$statusCode == 200"
},
{
"condition": "$response.body.id == $steps.createPlan.outputs.planId"
},
{
"condition": "$response.body.distributed == true"
}
],
"outputs": {
"planId": "$response.body#/id",
"distributed": "$response.body#/distributed",
"routeIds": "$response.body#/routes"
}
}
],
"outputs": {
"driverId": "$steps.createDriver.outputs.driverId",
"planId": "$steps.distributePlan.outputs.planId",
"stopId": "$steps.createStop.outputs.stopId",
"operationId": "$steps.optimizePlan.outputs.operationId",
"optimizationResult": "$steps.waitForOptimization.outputs.result",
"routeIds": "$steps.distributePlan.outputs.routeIds",
"distributed": "$steps.distributePlan.outputs.distributed"
},
"description": "Start with a fictional team whose Main Depot and normal working hours are configured and whose subscription supports the demonstrated workflow. Use a new driver email and the current local plan date. Driver creation uses exactly one contact method: email, not phone. Explicit route start/end coordinates and reachable delivery addresses avoid relying on a depot location. Add stops individually, repeating the add-stop request for further deliveries before optimization. End with the same plan distributed and route IDs available. Pending optimization is normal; failures, cancellation and skipped stops stop this golden path. Distribution always requires an explicit action. Intended execution is browser-local simulation only.",
"x-spoke-demo": {
"completionMessage": "Simulated distribution complete",
"outcome": {
"title": "Ready to distribute",
"description": "Review these details, then run the simulated distribution request when ready. No real driver notification is sent.",
"fields": [
{
"label": "Plan",
"stepId": "createPlan",
"pointer": "/title"
},
{
"label": "Driver",
"stepId": "createDriver",
"pointer": "/name"
},
{
"label": "Routes",
"stepId": "reviewPlan",
"pointer": "/routes"
}
]
}
}
}
]
}