Dispatch pause & resume

These endpoints hold and release outbound dispatch. Read Dispatch pacing first for the model: what each scope holds, why pause is never cancel, and how automatic backoffs share the same records. Access follows one rule everywhere: pause and resume writes require an admin role on your organization; listings and single-record reads are open to any organization member. A Domain, batch, or pause ID that belongs to another organization returns 404, never 403.

The pause record

Every endpoint below reads or writes the same record shape:

{
  "id": "pause_9f2c1a7b3d4e5f60",
  "scope": "domain",
  "tenancy_id": "ten_9f2c1a7b3d4e5f60",
  "lane": null,
  "bucket": null,
  "batch_id": null,
  "status": "active",
  "cause": "admin_request",
  "reason": "Provider maintenance window",
  "created_by": "user_11223344",
  "created_at": "2026-07-29T12:00:00Z",
  "expires_at": "2026-07-29T13:00:00Z",
  "released_at": null,
  "released_by": null,
  "extensions": []
}

Field	Meaning
`scope`	`global`, `domain`, `lane`, `bucket`, or `batch`. Exactly one target field below is set to match.
`tenancy_id` / `lane` / `bucket` / `batch_id`	What is held. `bucket`-scope records are opened only by automatic rate-limit backoff — you cannot create one.
`status`	`active` while the hold is in force, `released` afterwards. Releasing never deletes; the record survives as the audit trail.
`cause`	Machine-readable origin: `admin_request` for a human hold, a provider fault tag for an automatic backoff.
`reason`	The optional human note supplied at pause time.
`created_by`, `created_at`	Who opened the hold and when. API-key callers are attributed as the account.
`expires_at`	The scheduled automatic resume, if a duration was given; `null` for an open-ended hold.
`released_at`, `released_by`	Set once the hold is released — by an admin, or by the scheduler when `expires_at` passes.
`extensions`	One entry per time the scheduled resume was pushed out.

Pause request body

All create endpoints accept the same body; every field is optional.

Field	Constraints
`duration_seconds`	Integer, `1` to `604800` (one week). Schedules an automatic resume; omit for an open-ended hold.
`reason`	String, at most `500` characters. Free-text audit note.
`lane`	Domain endpoint only — one of `backfill`, `bulk`, `compliance`, `interactive`. Narrows the hold to that lane.
`bucket`	Never accepted on these endpoints (`422`) — bucket holds are the automatic backoff’s shape.

Global (break-glass)

Holds every Domain in your organization at once. Prefer the Domain, lane, or batch endpoints when anything narrower will do.

Method	Endpoint	Access	Success
`POST`	`/admin/dispatch/pause`	Admin	`201` — the new `global`-scope record
`POST`	`/admin/dispatch/resume`	Admin	`200` — the released records (`[]` when nothing was held)
`GET`	`/admin/dispatch/pauses`	Any member	`200` — a page of your organization’s pause records, all scopes, admin holds and automatic backoffs alike
`GET`	`/admin/dispatch/pauses/{pause_id}`	Any member	`200` — one record with its full audit trail

The break-glass pause accepts duration_seconds and reason only. A body carrying lane or bucket is refused with 422 rather than silently widened to global — if you meant a narrower hold, use the narrower endpoint. Resume releases every active global hold and returns them; holds at Domain, lane, or batch scope are untouched. It is idempotent: resuming when nothing is held returns an empty list, not an error.

curl -X POST "$BASE_URL/admin/dispatch/pause" \
  -H "X-API-Key: $GETDIALED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"duration_seconds": 3600, "reason": "Provider maintenance window"}'

The listing supports include_released (default false), a scope filter, sort_by (created_at or expires_at), order (asc/desc, default desc), and limit (1–500, default 100) / skip pagination.

Domain and lane

Holds one Five9 Domain — or one named lane on it. These are records only: no batch document is rewritten and nothing in the queue is touched; the hold is visible here and on the pause listing.

Method	Endpoint	Access	Success
`POST`	`/platforms/five9/domains/{tenancy_id}/pause`	Admin	`201` — a `domain`-scope record, or a `lane`-scope record when the body carries `lane`
`POST`	`/platforms/five9/domains/{tenancy_id}/resume`	Admin	`200` — the released records (`[]` when nothing was held)
`GET`	`/platforms/five9/domains/{tenancy_id}/pauses`	Any member	`200` — a page of this Domain’s holds, admin holds and automatic backoffs alike
`PATCH`	`/platforms/five9/domains/{tenancy_id}/pauses/{pause_id}`	Admin	`200` — the extended record

Pausing without lane holds the whole Domain; with lane, only that lane, while the rest of the Domain keeps flowing. A bucket in the body is refused with 422 — bucket holds are opened automatically by rate-limit backoff and cannot be created here. Resume mirrors pause’s scoping: without a lane it releases the Domain-wide holds only; with ?lane=bulk (query parameter) it releases that lane’s holds only, leaving any Domain-wide hold in force. An unknown lane is a 422. Automatic backoffs are never released here — they self-resume at the window boundary.

curl -X POST "$BASE_URL/platforms/five9/domains/ten_9f2c1a7b3d4e5f60/pause" \
  -H "X-API-Key: $GETDIALED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"lane": "bulk", "reason": "Campaign under review"}'

Extending a scheduled resume

PATCH .../pauses/{pause_id} pushes a pause’s scheduled resume further out, in place — the record keeps its identity and gains an entry in extensions. Provide duration_seconds (relative to now) or an absolute expires_at; when both are sent, the absolute expires_at wins. Extension is forward-only. Three cases return 409, each with its own message: the record is already released; the requested expiry is not later than the current one; or the record changed concurrently between your read and the write. Shortening a hold is an explicit resume-and-re-pause, never a silent edit. An explicit JSON null for a field is rejected with 422 — omit the field instead.

curl -X PATCH "$BASE_URL/platforms/five9/domains/ten_9f2c1a7b3d4e5f60/pauses/pause_9f2c1a7b3d4e5f60" \
  -H "X-API-Key: $GETDIALED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"duration_seconds": 1800}'

Batch

The one scope that touches a batch’s status: pausing flips the batch to paused, and resuming restores the exact status it held before — a batch paused while queued goes back to queued. Nothing is cancelled or deleted, and nothing already sent can be re-sent.

Method	Endpoint	Access	Success
`POST`	`/batches/{batch_id}/pause`	Admin	`201` — the `batch`-scope record
`POST`	`/batches/{batch_id}/resume`	Admin	`200` — the released records (`[]` when nothing was held)

The pause body accepts duration_seconds and reason only; lane or bucket is refused with 422 — those scopes belong to the Domain endpoints. Pausing an already-paused batch is idempotent and returns the existing hold. A batch in a terminal state (completed, partially_failed, failed, cancelled) has nothing left to dispatch and returns 409; a 409 also comes back if the batch’s status changed concurrently while the pause was being applied — re-read the batch and retry.

curl -X POST "$BASE_URL/batches/batch_53c124a15e6e47fe/pause" \
  -H "X-API-Key: $GETDIALED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Uploaded against the wrong list"}'

Errors

All endpoints use the standard {"detail": "..."} envelope.

Status	When
`401`	Missing or invalid credentials.
`403`	Authenticated but not an admin, on any pause/resume/extend write.
`404`	The Domain, batch, or pause does not exist — or belongs to another organization (never `403`).
`409`	Extension refused (released record, non-later expiry, or concurrent change), or a batch pause hit a terminal/concurrently-changed batch.
`422`	Validation: `duration_seconds` outside `1`–`604800`, `reason` over `500` characters, an unknown `lane`, a `bucket` in any body, `lane`/`bucket` on the global or batch endpoints, or an explicit `null` on the extension PATCH.
`429`	Request rate limit exceeded — retry after the `Retry-After` header.

Overview

Endpoints

The pause record

Pause request body

Global (break-glass)

Domain and lane

Extending a scheduled resume

Batch

Errors

​The pause record

​Pause request body

​Global (break-glass)

​Domain and lane

​Extending a scheduled resume

​Batch

​Errors

The pause record

Pause request body

Global (break-glass)

Domain and lane

Extending a scheduled resume

Batch

Errors