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
requestspackage.
Steps #
- Open Settings, then Integration keys. Name the key, choose the scope
userfor this quickstart (usereadfor a reporting tool), and make it. Copy the key. It starts withpsdt_and shows once. - Keep the key out of your code. Put it in an environment variable called
POP_TOKEN. - 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"
- List customers. The answer is a page:
dataholds the customers andnext_cursoris null on the last page. Send it back ascursorfor 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"])
- Create a tow call with
POST /tow/calls. Onlypickup_addris required. Send anIdempotency-Keyso a retry cannot create the call twice. The answer is 201 with the call indata, and its status starts asnew.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"])
- Read errors by
code, never by the message text. A failed call answers{"error": {"code": ..., "message": ..., "request_id": ...}}. Keep therequest_idwhen you contact support. - When a call answers 429, wait the number of seconds in the
Retry-Afterheader and send it again.
Choosing a scope #
read: reading only. A write answersforbidden.dispatch: towing and the driver app, plus reading customers and vehicles.userandfull: 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
forbiddenwith "This key is read-only.": use auserorfullkey for writes. - 403
forbiddenwith "This key is for towing dispatch only.": the call is outside the dispatch scope. - 422
validation_failed: readfieldsin the error to see which values to fix. - 409
conflicton a repeated key: the same Idempotency-Key was used for a different request. Make a new key for a new request.