Optiway API

Optiway Dispatch 4 min read Updated Nov 17, 2026

Overview

The Optiway API lets your order system, store or spreadsheet send stops straight into Optiway Dispatch, and lets you find out when drivers deliver them. Stops you create through the API land in your unassigned stops, ready to plan into routes in the dashboard.

The base URL is https://api.optiway-app.com/v1. Requests and responses are JSON over HTTPS. Field names use snake_case and timestamps are ISO 8601 in UTC.

Authentication

Create an API key in the dashboard under Workspace settings → API keys. Only the account owner can create keys. The key is shown once, so store it somewhere safe. A key acts on behalf of your workspace; revoke it on the same page and it stops working right away.

Send the key in the Authorization header of every request:

Authorization: Bearer opw_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Get your workspace

GET /v1/me returns the workspace the key belongs to. Use it to check that a key works.

curl https://api.optiway-app.com/v1/me \
  -H "Authorization: Bearer $OPTIWAY_API_KEY"
{
  "organization_id": 342,
  "organization_name": "Acme Deliveries",
  "email": "owner@acme.com"
}

Create a stop

POST /v1/stops adds an unassigned stop.

FieldTypeDescription
addressstring, requiredFull delivery address with city and postal code. Optiway finds it on the map, near your default start location.
lat, lonnumberCoordinates. Send both to skip the address lookup.
external_idstringYour order or reference number, up to 191 characters.
recipient_namestringWho receives the delivery.
phonestringRecipient phone number.
notesstringInstructions the driver sees.
parcel_numberstringParcel or package number.
curl -X POST https://api.optiway-app.com/v1/stops \
  -H "Authorization: Bearer $OPTIWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "20 W 34th St, New York, NY 10001",
    "external_id": "order-1001",
    "recipient_name": "Jane Smith",
    "phone": "+15550000000",
    "notes": "Leave at the front desk"
  }'

The response is the created stop.

Safe retries. If you send external_id and a stop with that ID already exists in your workspace, Optiway returns the existing stop instead of creating a second one, and it does not count against your monthly stop limit again. Always send external_id when you can.

Every stop created through the API counts towards your plan's monthly stop limit, the same as a stop added in the dashboard.

List delivered and failed stops

GET /v1/stops?status=completed returns stops that drivers marked as delivered in the last 7 days, newest first. Use status=failed for stops marked as not delivered.

ParameterDescription
statusRequired. completed or failed.
limitHow many stops to return, 1 to 100. Default 50.
curl "https://api.optiway-app.com/v1/stops?status=completed&limit=20" \
  -H "Authorization: Bearer $OPTIWAY_API_KEY"
{
  "data": [
    { "id": 7480042, "external_id": "order-1001", "status": "completed", ... }
  ]
}

To react to deliveries, poll this endpoint every few minutes and remember the id values you have already processed.

The stop object

FieldDescription
idOptiway stop ID.
external_idYour order ID, if you sent one.
statusunassigned, assigned, in_progress, completed or failed. New values may be added.
address, lat, lonWhere the stop is on the map.
recipient_name, phone, notes, parcel_numberAs sent when the stop was created or edited in the dashboard.
driver_nameThe driver the stop's route is assigned to.
completed_atWhen the driver completed or failed the stop.
failure_reasonWhy a stop failed, for example CUSTOMER_NOT_AVAILABLE.
driver_noteThe note the driver left at the stop.
created_atWhen the stop was created.

Ignore fields you don't use: new fields may appear in responses without notice.

Errors and limits

Errors return a JSON body with a stable code and an English message:

{ "code": "address_not_found", "message": "The address could not be found" }
StatusCodeMeaning
400invalid_requestThe body is not valid JSON.
401unauthorizedThe API key is missing, wrong or revoked.
402quota_exceededYour monthly stop limit is reached.
422validation_failedA field is missing or invalid; the message says which.
422address_not_foundThe address could not be found on the map. Check it or send lat and lon.
422start_location_requiredAdd a start location in the dashboard, or send coordinates.
429rate_limitedMore than 60 requests in a minute with one key. Wait for Retry-After seconds.

A stop is never created when a request fails, so it is safe to fix the request and send it again.

Zapier

Optiway has a Zapier integration built on this API. It adds a Create Stop action and Stop Completed and Stop Failed triggers, so you can send orders from Shopify, Google Sheets or a form into Optiway and update them when drivers deliver, without writing code. To connect it, paste an API key when Zapier asks for your Optiway account.

The integration is invite-only for now. Write to support and we'll send you the invite link.

Questions or a use case the API doesn't cover yet? Write to support@optiway-app.com.