Get started
Color

API quickstart in curl, JavaScript and Python

Make an integration key, make your first call, list customers, create a tow call safely and read the answers, with code in curl, JavaScript and Python.

For
OwnerAdministrator
Hosting
Any hosting
Devices
All devices
Business
All businesses

Checked against Pop Dispatch 0.1.0

You will make a key, check that it works, list customers and create a tow call, each in curl, JavaScript and Python. It takes about ten minutes. The full reference is on your server's Developers page.

Before you start #

  • You need the owner or manager role to make a key.
  • Your server's address. The examples call it https://dispatch.example.com; use your own.
  • curl, Node 18 or newer for JavaScript, and Python with the requests package.

Steps #

  1. Open Settings, then Integration keys. Name the key, choose the scope user for this quickstart (use read for a reporting tool), and make it. Copy the key. It starts with psdt_ and shows once.
  2. Keep the key out of your code. Put it in an environment variable called POP_TOKEN.
  3. Check the key with GET /me. A good answer shows your role.
    curl -sS https://dispatch.example.com/api/v1/me -H "Authorization: Bearer $POP_TOKEN"
  1. List customers. The answer is a page: data holds the customers and next_cursor is null on the last page. Send it back as cursor for the next page.
    curl -sS "https://dispatch.example.com/api/v1/customers?q=smith&limit=25" -H "Authorization: Bearer $POP_TOKEN"
    const res = await fetch("https://dispatch.example.com/api/v1/customers?q=smith&limit=25", {
      headers: { Authorization: `Bearer ${process.env.POP_TOKEN}` },
    });
    const page = await res.json();
    for (const c of page.data) console.log(c.id, c.name);
    import os, requests
    res = requests.get("https://dispatch.example.com/api/v1/customers",
                       headers={"Authorization": f"Bearer {os.environ['POP_TOKEN']}"},
                       params={"q": "smith", "limit": 25}, timeout=15)
    for c in res.json()["data"]:
        print(c["id"], c["name"])
  1. Create a tow call with POST /tow/calls. Only pickup_addr is required. Send an Idempotency-Key so a retry cannot create the call twice. The answer is 201 with the call in data, and its status starts as new.
    curl -sS https://dispatch.example.com/api/v1/tow/calls \
      -H "Authorization: Bearer $POP_TOKEN" -H "Content-Type: application/json" \
      -H "Idempotency-Key: $(uuidgen)" \
      -d '{"pickup_addr": "120 Main St, Springfield", "reason": "breakdown"}'
    import { randomUUID } from "node:crypto";
    const res = await fetch("https://dispatch.example.com/api/v1/tow/calls", {
      method: "POST",
      headers: { Authorization: `Bearer ${process.env.POP_TOKEN}`, "Content-Type": "application/json", "Idempotency-Key": randomUUID() },
      body: JSON.stringify({ pickup_addr: "120 Main St, Springfield", reason: "breakdown" }),
    });
    console.log(res.status, (await res.json()).data.number);
    import os, uuid, requests
    res = requests.post("https://dispatch.example.com/api/v1/tow/calls",
                        headers={"Authorization": f"Bearer {os.environ['POP_TOKEN']}", "Idempotency-Key": str(uuid.uuid4())},
                        json={"pickup_addr": "120 Main St, Springfield", "reason": "breakdown"}, timeout=15)
    print(res.status_code, res.json()["data"]["number"])
  1. Read errors by code, never by the message text. A failed call answers {"error": {"code": ..., "message": ..., "request_id": ...}}. Keep the request_id when you contact support.
  2. When a call answers 429, wait the number of seconds in the Retry-After header and send it again.

Choosing a scope #

  • read: reading only. A write answers forbidden.
  • dispatch: towing and the driver app, plus reading customers and vehicles.
  • user and full: everything the key owner's role allows.
Technical details
  • Every request line is at most 2000 characters. A token is checked on every call, so ending a key in Settings, Integration keys stops it at once.
  • Limits: 300 requests a minute for each key and 600 for each network address.
  • The Idempotency-Key is 8 to 80 characters. Repeating the same request returns the stored answer with the header Idempotent-Replay: true.
  • The sign-in route, POST /auth/login, returns a token for a person with a password. Use a key for another system, because a key can be limited by scope and ended on its own.

If something goes wrong #

  • 401 unauthorized: the key is missing, ended, expired or typed wrongly. Make a new one.
  • 403 forbidden with "This key is read-only.": use a user or full key for writes.
  • 403 forbidden with "This key is for towing dispatch only.": the call is outside the dispatch scope.
  • 422 validation_failed: read fields in the error to see which values to fix.
  • 409 conflict on a repeated key: the same Idempotency-Key was used for a different request. Make a new key for a new request.