Rewind segments

Generated from DialerDigital/core commit 0fc18008b3c8 — spec openapi/dialer-v1.yaml v0.134.0. Do not edit by hand; see How this reference is built. Download the OpenAPI spec.

Español

Named sets of rewind filters a supervisor saves per tenant and re-uses (the filters, never a list of accounts).

Endpoints

Method	Path	Summary
GET	/v1/rewind-segments	The tenant's saved rewind segments
POST	/v1/rewind-segments	Save a named set of rewind filters
PATCH	/v1/rewind-segments/{id}	Rename a segment or replace its filters
POST	/v1/rewind-segments/{id}/retire	Retire a segment (terminal)

The tenant's saved rewind segments

GET /v1/rewind-segments

The live segments of the tenant, by name. Retired ones are not listed. A segment is a NAMED SET OF FILTERS, not a list of accounts: using it (segment_id on the rewind) re-evaluates it against the data of that moment, so no second copy of PII exists.

Responses

200

The live segments.

Field	Type	Required	Description
rewind_segments	array of RewindSegment	yes
rewind_segments[].id	string (uuid)	yes
rewind_segments[].name	string	yes
rewind_segments[].filters	object (RewindFilters)	yes	All filters optional; unknown amd_verdicts answer 422 fail-closed.
rewind_segments[].filters.dispositions	array of string	no	Matched against each debt's LATEST disposition.
rewind_segments[].filters.max_attempts	integer	no	Count of original attempts.
rewind_segments[].filters.last_attempt_older_than_days	integer	no
rewind_segments[].filters.keep_scheduled_callbacks	boolean	no	false cancels the campaign's pending callbacks for the rewound debts (rewind only).
rewind_segments[].filters.amd_verdicts	array of unspecified · human · machine · not_sure	no	Matched against the latest placed attempt's AMD verdict.
rewind_segments[].created_by	string	yes	Taken from the credential, never from the body.
rewind_segments[].created_at	string (date-time)	yes
rewind_segments[].updated_at	string (date-time)	yes
rewind_segments[].retired_at	string (date-time) | null	yes
rewind_segments[].retired_by	string | null	yes

401 — Unauthorized

Missing, unknown or revoked API key (or, on /v1/admin/*, a bad/unset admin token; on webhooks, a bad/missing signature). A dashboard session (ddu_) that a newer login of the same person ended answers the code session_superseded instead (tenant flag single_session_enforced), so the screen can say why it was signed out; a logout, an expired or an unknown token stay unauthorized.

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

429 — ApiKeyRateLimited

This API key is over its request quota, or the tenant's keys together are over the tenant ceiling (core#2503) (code rate_limited). The request was not processed. Wait Retry-After seconds and retry; a refusal is not counted against the budget, so that wait is always enough. Bounded per API key and, above the keys, per tenant (api_tenant_requests_per_minute): a sibling key is unaffected until the tenant's keys together reach that ceiling. The quota applies to every operation reachable with a dd_ key, so the operations that name a more specific 429 (call control, dispositions, SMS, …) can ALSO answer this one with its X-RateLimit-* headers.

{
  "error": {
    "code": "rate_limited",
    "message": "API key request quota exceeded; retry after the interval in Retry-After"
  }
}

Save a named set of rewind filters

POST /v1/rewind-segments

filters goes through the SAME validator as the rewind itself (Dialer.Campaigns.RewindFilters): a filter set the rewind would refuse is 422 here, and an unrecognized key is 422 naming it. name is trimmed, 1 to 80 characters, and unique among the tenant's LIVE segments without regard to case (409 conflict otherwise; a retired name is reusable). Who saved it is taken from the credential. Every write leaves an append-only audit fact (created / edited / retired).

Request body (JSON, required)

Field	Type	Required	Description
name	string	yes
filters	object (RewindFilters)	yes	All filters optional; unknown amd_verdicts answer 422 fail-closed.
filters.dispositions	array of string	no	Matched against each debt's LATEST disposition.
filters.max_attempts	integer	no	Count of original attempts.
filters.last_attempt_older_than_days	integer	no
filters.keep_scheduled_callbacks	boolean	no	false cancels the campaign's pending callbacks for the rewound debts (rewind only).
filters.amd_verdicts	array of unspecified · human · machine · not_sure	no	Matched against the latest placed attempt's AMD verdict.

{
  "name": "Voicemail, 3+ attempts, last week",
  "filters": {
    "dispositions": [
      "no_answer",
      "voicemail"
    ],
    "max_attempts": 3,
    "last_attempt_older_than_days": 7
  }
}

Responses

201

Saved.

Field	Type	Required	Description
rewind_segment	object (RewindSegment)	yes
rewind_segment.id	string (uuid)	yes
rewind_segment.name	string	yes
rewind_segment.filters	object (RewindFilters)	yes	All filters optional; unknown amd_verdicts answer 422 fail-closed.
rewind_segment.filters.dispositions	array of string	no	Matched against each debt's LATEST disposition.
rewind_segment.filters.max_attempts	integer	no	Count of original attempts.
rewind_segment.filters.last_attempt_older_than_days	integer	no
rewind_segment.filters.keep_scheduled_callbacks	boolean	no	false cancels the campaign's pending callbacks for the rewound debts (rewind only).
rewind_segment.filters.amd_verdicts	array of unspecified · human · machine · not_sure	no	Matched against the latest placed attempt's AMD verdict.
rewind_segment.created_by	string	yes	Taken from the credential, never from the body.
rewind_segment.created_at	string (date-time)	yes
rewind_segment.updated_at	string (date-time)	yes
rewind_segment.retired_at	string (date-time) | null	yes
rewind_segment.retired_by	string | null	yes

400 — BadRequest

Malformed request (shape/type errors, invalid filters, bad timestamps).

{
  "error": {
    "code": "bad_request",
    "message": "from must be RFC-3339"
  }
}

401 — Unauthorized

Missing, unknown or revoked API key (or, on /v1/admin/*, a bad/unset admin token; on webhooks, a bad/missing signature). A dashboard session (ddu_) that a newer login of the same person ended answers the code session_superseded instead (tenant flag single_session_enforced), so the screen can say why it was signed out; a logout, an expired or an unknown token stay unauthorized.

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

409 — Conflict

Invalid state transition, uniqueness conflict, or a seat that is busy/reserved.

{
  "error": {
    "code": "conflict",
    "message": "invalid state transition"
  }
}

422 — Unprocessable

Shape is fine, semantics are not (broken domain rule).

{
  "error": {
    "code": "unprocessable",
    "message": "scheduled_at is closer than the minimum notice for a callback (10 minutes unless the tenant's callback_min_notice_seconds says otherwise)"
  }
}

429 — ApiKeyRateLimited

This API key is over its request quota, or the tenant's keys together are over the tenant ceiling (core#2503) (code rate_limited). The request was not processed. Wait Retry-After seconds and retry; a refusal is not counted against the budget, so that wait is always enough. Bounded per API key and, above the keys, per tenant (api_tenant_requests_per_minute): a sibling key is unaffected until the tenant's keys together reach that ceiling. The quota applies to every operation reachable with a dd_ key, so the operations that name a more specific 429 (call control, dispositions, SMS, …) can ALSO answer this one with its X-RateLimit-* headers.

{
  "error": {
    "code": "rate_limited",
    "message": "API key request quota exceeded; retry after the interval in Retry-After"
  }
}

Rename a segment or replace its filters

PATCH /v1/rewind-segments/{id}

filters, when sent, REPLACES the stored set (it does not merge). Sending neither name nor filters is 400; an edit that changes nothing is 200 and writes no audit fact. A retired, missing or another tenant's segment is 404. Same validation and status codes as the POST.

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	yes	Resource UUID. Malformed or cross-tenant ids read as 404.

Request body (JSON, required)

Field	Type	Required	Description
name	string	no
filters	object (RewindFilters)	no	All filters optional; unknown amd_verdicts answer 422 fail-closed.
filters.dispositions	array of string	no	Matched against each debt's LATEST disposition.
filters.max_attempts	integer	no	Count of original attempts.
filters.last_attempt_older_than_days	integer	no
filters.keep_scheduled_callbacks	boolean	no	false cancels the campaign's pending callbacks for the rewound debts (rewind only).
filters.amd_verdicts	array of unspecified · human · machine · not_sure	no	Matched against the latest placed attempt's AMD verdict.

Responses

200

Updated.

Field	Type	Required	Description
rewind_segment	object (RewindSegment)	yes
rewind_segment.id	string (uuid)	yes
rewind_segment.name	string	yes
rewind_segment.filters	object (RewindFilters)	yes	All filters optional; unknown amd_verdicts answer 422 fail-closed.
rewind_segment.filters.dispositions	array of string	no	Matched against each debt's LATEST disposition.
rewind_segment.filters.max_attempts	integer	no	Count of original attempts.
rewind_segment.filters.last_attempt_older_than_days	integer	no
rewind_segment.filters.keep_scheduled_callbacks	boolean	no	false cancels the campaign's pending callbacks for the rewound debts (rewind only).
rewind_segment.filters.amd_verdicts	array of unspecified · human · machine · not_sure	no	Matched against the latest placed attempt's AMD verdict.
rewind_segment.created_by	string	yes	Taken from the credential, never from the body.
rewind_segment.created_at	string (date-time)	yes
rewind_segment.updated_at	string (date-time)	yes
rewind_segment.retired_at	string (date-time) | null	yes
rewind_segment.retired_by	string | null	yes

400 — BadRequest

Malformed request (shape/type errors, invalid filters, bad timestamps).

{
  "error": {
    "code": "bad_request",
    "message": "from must be RFC-3339"
  }
}

401 — Unauthorized

Missing, unknown or revoked API key (or, on /v1/admin/*, a bad/unset admin token; on webhooks, a bad/missing signature). A dashboard session (ddu_) that a newer login of the same person ended answers the code session_superseded instead (tenant flag single_session_enforced), so the screen can say why it was signed out; a logout, an expired or an unknown token stay unauthorized.

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

404 — NotFound

Unknown id, malformed (non-UUID) id OR another tenant's id — RLS returns zero rows, so all three are indistinguishable by design (no existence leak, never a 403 for foreign ids).

{
  "error": {
    "code": "not_found",
    "message": "resource not found for this tenant"
  }
}

409 — Conflict

Invalid state transition, uniqueness conflict, or a seat that is busy/reserved.

{
  "error": {
    "code": "conflict",
    "message": "invalid state transition"
  }
}

422 — Unprocessable

Shape is fine, semantics are not (broken domain rule).

{
  "error": {
    "code": "unprocessable",
    "message": "scheduled_at is closer than the minimum notice for a callback (10 minutes unless the tenant's callback_min_notice_seconds says otherwise)"
  }
}

429 — ApiKeyRateLimited

This API key is over its request quota, or the tenant's keys together are over the tenant ceiling (core#2503) (code rate_limited). The request was not processed. Wait Retry-After seconds and retry; a refusal is not counted against the budget, so that wait is always enough. Bounded per API key and, above the keys, per tenant (api_tenant_requests_per_minute): a sibling key is unaffected until the tenant's keys together reach that ceiling. The quota applies to every operation reachable with a dd_ key, so the operations that name a more specific 429 (call control, dispositions, SMS, …) can ALSO answer this one with its X-RateLimit-* headers.

{
  "error": {
    "code": "rate_limited",
    "message": "API key request quota exceeded; retry after the interval in Retry-After"
  }
}

Retire a segment (terminal)

POST /v1/rewind-segments/{id}/retire

Logical retirement: the row stays (and its audit trail with it), it leaves the list, and it can no longer be used or edited. Nothing is ever deleted. Retiring again is 404.

Parameters

Name	In	Type	Required	Description
id	path	string (uuid)	yes	Resource UUID. Malformed or cross-tenant ids read as 404.

Responses

200

Retired.

Field	Type	Required	Description
rewind_segment	object (RewindSegment)	yes
rewind_segment.id	string (uuid)	yes
rewind_segment.name	string	yes
rewind_segment.filters	object (RewindFilters)	yes	All filters optional; unknown amd_verdicts answer 422 fail-closed.
rewind_segment.filters.dispositions	array of string	no	Matched against each debt's LATEST disposition.
rewind_segment.filters.max_attempts	integer	no	Count of original attempts.
rewind_segment.filters.last_attempt_older_than_days	integer	no
rewind_segment.filters.keep_scheduled_callbacks	boolean	no	false cancels the campaign's pending callbacks for the rewound debts (rewind only).
rewind_segment.filters.amd_verdicts	array of unspecified · human · machine · not_sure	no	Matched against the latest placed attempt's AMD verdict.
rewind_segment.created_by	string	yes	Taken from the credential, never from the body.
rewind_segment.created_at	string (date-time)	yes
rewind_segment.updated_at	string (date-time)	yes
rewind_segment.retired_at	string (date-time) | null	yes
rewind_segment.retired_by	string | null	yes

400 — BadRequest

Malformed request (shape/type errors, invalid filters, bad timestamps).

{
  "error": {
    "code": "bad_request",
    "message": "from must be RFC-3339"
  }
}

401 — Unauthorized

Missing, unknown or revoked API key (or, on /v1/admin/*, a bad/unset admin token; on webhooks, a bad/missing signature). A dashboard session (ddu_) that a newer login of the same person ended answers the code session_superseded instead (tenant flag single_session_enforced), so the screen can say why it was signed out; a logout, an expired or an unknown token stay unauthorized.

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

404 — NotFound

Unknown id, malformed (non-UUID) id OR another tenant's id — RLS returns zero rows, so all three are indistinguishable by design (no existence leak, never a 403 for foreign ids).

{
  "error": {
    "code": "not_found",
    "message": "resource not found for this tenant"
  }
}

429 — ApiKeyRateLimited

This API key is over its request quota, or the tenant's keys together are over the tenant ceiling (core#2503) (code rate_limited). The request was not processed. Wait Retry-After seconds and retry; a refusal is not counted against the budget, so that wait is always enough. Bounded per API key and, above the keys, per tenant (api_tenant_requests_per_minute): a sibling key is unaffected until the tenant's keys together reach that ceiling. The quota applies to every operation reachable with a dd_ key, so the operations that name a more specific 429 (call control, dispositions, SMS, …) can ALSO answer this one with its X-RateLimit-* headers.

{
  "error": {
    "code": "rate_limited",
    "message": "API key request quota exceeded; retry after the interval in Retry-After"
  }
}