Roldesk REST API

Create a token under Settings → Developer (owner/admin, Professional plan), then verify it:

curl https://www.roldesk.com/api/v1/me \
  -H "Authorization: Bearer rk_live_…"

List your work orders:

curl "https://www.roldesk.com/api/v1/work-orders?limit=25" \
  -H "Authorization: Bearer rk_live_…"

Pass your token as a Bearer credential on every request: Authorization: Bearer rk_live_…. Tokens are shown once at creation — store them securely. They can be created and revoked by an owner or admin under Settings → Developer, and are available on the Professional plan. The API is server-to-server (no cookies, no browser CORS credentials).

Each token is granted a subset of scopes. A scope is {group}:{read|write}. A token can never exceed what your plan allows.

Lists are cursor-paginated. Pass limit (1–100, default 25) and starting_after (the previous response's next_cursor).

{
  "data": [ { "object": "work_order", "id": "…", … } ],
  "has_more": true,
  "next_cursor": "eyJ…"
}

Most lists also accept allow-listed filters such as status, account_id, and updated_since.

Creates accept an Idempotency-Key header — retrying with the same key returns the original result instead of creating a duplicate. Updates accept expected_updated_at for optimistic concurrency; a stale value returns 409.

curl -X POST https://www.roldesk.com/api/v1/customers \
  -H "Authorization: Bearer rk_live_…" \
  -H "Idempotency-Key: create-acme-2026-08" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp", "email": "ops@acme.com"}'

Errors use a consistent envelope with the right HTTP status:

{ "error": { "type": "…", "code": "…", "message": "…", "param": "…" } }

Instead of polling, subscribe to events and we'll POST them to your server as they happen. Add an endpoint under Settings → Developer (or via the API for Zapier-style integrations), choose the events you care about, and store the signing secret we show once.

Each delivery is a JSON POST with these headers:

Roldesk-Event:      contract.renewed
Roldesk-Delivery:   <delivery id>
Roldesk-Signature:  t=<unix_ts>,v1=<hex hmac-sha256>

The body is a thin event — fetch the full object from the REST API using its id:

{ "id": "…", "type": "contract.renewed", "created": "2026-08-10T12:00:00Z",
  "data": { "object": "contract", "id": "…" } }

Verify the signature before trusting a delivery (Node):

import crypto from "crypto";

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map(p => p.split("=")));
  const expected = crypto.createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}

Failed deliveries retry with backoff (up to 6 attempts); an endpoint that keeps failing is auto-disabled. Available events:

Zapier & no-code: use the REST Hook pattern — your Zap subscribes with POST /api/v1/webhooks (a token with webhooks:write) and unsubscribes with DELETE /api/v1/webhooks/{id}.

The complete machine-readable definition lives at /api/v1/openapi.json (OpenAPI 3.1) — import it into Postman, Insomnia, or your codegen tool.

New to it? Step-by-step guides live in the Help Center — getting started, webhooks, Zapier, and common recipes.