Dispatch via API

Overview

The dispatch API is Rundun's core B2B integration point. Your property management system, booking platform, or fleet software dispatches a checklist run with a single API call and receives results via webhook — without building any mobile UI yourself.

The executor receives a link (via your existing communication channel — iMessage, WhatsApp, email), opens it in the Rundun app, completes the checklist, and your backend is notified in real time.

Dispatching a run

curl -X POST https://api.rundun.app/v1/runs \
  -H "Authorization: Bearer rdk_live_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "t-550e8400-e29b-41d4-a716-446655440000",
    "webhook": {
      "url": "https://your-app.com/hooks/rundun",
      "secret": "whsec_your-secret",
      "events": ["run.completed", "run.cancelled"]
    },
    "expires_in_hours": 24,
    "executor_ref": "booking_12345"
  }'

Request fields

Field	Required	Description
`template_id`	Yes	ID of the template to run. Snapshotted at dispatch time.
`webhook.url`	No	Your endpoint to receive events.
`webhook.secret`	No	HMAC secret for signature verification.
`webhook.events`	No	Which events to receive. Defaults to all.
`expires_in_hours`	No	Link validity. Default 72 hours.
`executor_ref`	No	Your own reference (booking ID, reservation number). Stored on the run, returned in webhooks.

Response

{
  "run_id": "r-7a3f9b00-e29b-41d4-a716-446655440000",
  "link": "https://rundun.app/r/r-7a3f9b00-e29b-41d4-a716-446655440000",
  "expires_at": "2026-05-23T09:00:00Z",
  "assigned_to": null
}

Send the link to your executor via any communication channel. When the executor opens the link and completes the checklist, your webhook endpoint receives the results.

Retrieving a completed run

GET /v1/runs/r-7a3f9b00-...
Authorization: Bearer rdk_live_your-api-key

Returns the full run document including all answers, photo URLs, GPS coordinates, timestamps, and executor identity.

API keys

API keys are org-scoped and created in my.rundun.app under Settings → API keys. The key format is rdk_live_ followed by 32 random characters. The full key is shown once at creation — Rundun stores only the SHA-256 hash.

Every resource created via an API key is owned by the key's organization. Run credits are consumed from that organization's balance.

Using executor_ref for correlation

The executor_ref field lets you attach your own identifier to a run. This string is returned in every webhook for this run, making it trivial to correlate Rundun events with your own records without maintaining a separate run ID mapping:

{
  "event": "run.completed",
  "run_id": "r-7a3f9b00-...",
  "data": {
    "executor_ref": "booking_12345",
    "answers": { ... }
  }
}

Template snapshots

When you dispatch a run, the template is snapshotted verbatim into the run document. Subsequent changes to the template do not affect in-progress runs. This means you can safely update your templates at any time without breaking active dispatches.

Run expiry

If an executor doesn't open the link before expires_at, the run is marked expired and a run.expired webhook fires (if subscribed). The link stops working. Dispatch a new run to retry.