OTP approvals workflow

This guide assembles the two-officer approval loop for Verify end to end: turn the gate on, queue a change, take a decision, watch it execute, and wire the notifications. The per-field reference lives in OTP approvals; the setup walkthrough is Second-officer approvals for Verify. Use this page when you want the whole loop — policy, queue, decision, execution, webhooks — in one run-through with worked curl on every route.

The five-route group

The approvals API is one group of five routes under /api/v1/verify/approvals:

Route	Role	Purpose
`GET /api/v1/verify/approvals/settings`	any authenticated member	Read the policy. A requester calls this to predict whether their next template edit or resend burst will queue.
`PUT /api/v1/verify/approvals/settings`	owner/admin	Update the policy: the master switch, the optional resend-burst threshold, and the burst window.
`GET /api/v1/verify/approvals/pending`	owner/admin	List the queue, oldest first. Optional `limit` (1–100, default 50) and `kind` (`otp_template` or `resend_burst`).
`POST /api/v1/verify/approvals/:id/approve`	owner/admin, not the requester	Release the queued item.
`POST /api/v1/verify/approvals/:id/reject`	owner/admin	Hold the item, with an optional `reason` for the requester.

The same surface is in the dashboard at Outbound → OTP approvals — the queue and the Policy card sit on one page, and only owners and admins see it.

The two-officer workflow

The loop branches through create → review → commit:

Create. A requester edits an OTP template or drives resends past the configured burst threshold. Their change queues as a pending row instead of applying. A requester who reads GET /settings first can predict this.
Review. An approver (an owner or admin who is not the requester) opens Outbound → OTP approvals or lists GET /pending. Template rows show the exact rendered body to judge; burst rows show the count and window.
Commit. The approver posts approve (release) or reject (hold, optional reason). Approving as the requester returns 409 FOUR_EYES_VIOLATION and nothing moves. Approved items execute — the template goes live, or the burst re-enters the normal dispatch chain. Rejected items stop; the requester may re-submit, which queues a fresh row.

Worked curl across the loop

1. Read the policy (requester)

curl -X GET 'https://api.orbit.devotel.io/api/v1/verify/approvals/settings' \
  -H 'X-API-Key: dv_live_sk_your_key_here'

200

{
  "data": {
    "require_approval_default": false,
    "resend_burst_threshold": null,
    "resend_burst_window_seconds": 60
  },
  "meta": {
    "request_id": "req_0a1b2c",
    "timestamp": "2026-09-05T12:00:00.000Z"
  }
}

2. Set the policy (approver)

Send require_approval_default on every update — it is required. resend_burst_threshold accepts a positive integer or null (gate every burst); the window defaults to 60 seconds (max 86,400).

curl -X PUT 'https://api.orbit.devotel.io/api/v1/verify/approvals/settings' \
  -H 'X-API-Key: dv_live_sk_your_key_here' \
  -H 'Content-Type: application/json' \
  -d '{"require_approval_default": true, "resend_burst_threshold": 25, "resend_burst_window_seconds": 300}'

200

{
  "data": {
    "require_approval_default": true,
    "resend_burst_threshold": 25,
    "resend_burst_window_seconds": 300
  },
  "meta": {
    "request_id": "req_9f8e7d",
    "timestamp": "2026-09-05T12:05:00.000Z"
  }
}

3. Review the queue (approver)

curl -X GET 'https://api.orbit.devotel.io/api/v1/verify/approvals/pending?limit=50' \
  -H 'X-API-Key: dv_live_sk_your_key_here'

200

{
  "data": {
    "items": [
      {
        "id": "vap_01jxm1p8qf2ek9xtfa0kwewb4n",
        "kind": "resend_burst",
        "template_id": null,
        "verification_id": "vrf_02a4e7cfd7b54f0a94db3382b42d0db1",
        "burst_count": 9,
        "window_seconds": 300,
        "requested_by_user_id": "usr_0f3b1c…",
        "request_note": "retry the failed resend before the verification expires",
        "status": "pending",
        "created_at": "2026-08-23T10:11:00.000Z"
      }
    ]
  },
  "meta": {
    "request_id": "req_3c4d5e",
    "timestamp": "2026-09-05T12:10:00.000Z"
  }
}

4a. Commit: approve

curl -X POST 'https://api.orbit.devotel.io/api/v1/verify/approvals/vap_01jxm1p8qf2ek9xtfa0kwewb4n/approve' \
  -H 'X-API-Key: dv_live_sk_your_key_here'

200

{
  "data": {
    "approval_id": "vap_01jxm1p8qf2ek9xtfa0kwewb4n",
    "status": "approved"
  },
  "meta": {
    "request_id": "req_6f7a8b",
    "timestamp": "2026-09-05T12:15:00.000Z"
  }
}

If the approver is the requester, this returns 409 FOUR_EYES_VIOLATION and nothing is recorded.

4b. Commit: reject

The body is optional; reason goes back to the requester.

curl -X POST 'https://api.orbit.devotel.io/api/v1/verify/approvals/vap_01jxm1p8qf2ek9xtfa0kwewb4n/reject' \
  -H 'X-API-Key: dv_live_sk_your_key_here' \
  -H 'Content-Type: application/json' \
  -d '{"reason": "Template copy needs legal review before it goes live."}'

200

{
  "data": {
    "approval_id": "vap_01jxm1p8qf2ek9xtfa0kwewb4n",
    "status": "rejected"
  },
  "meta": {
    "request_id": "req_1a2b3c",
    "timestamp": "2026-09-05T12:20:00.000Z"
  }
}

Webhooks and idempotency

There is no approvals-specific webhook event. Downstream notification rides the standard Verify events: an approved resend burst emits the ordinary verification.sent event as it dispatches, and an approved template shows up in the ordinary verification events of its next transmission. Subscribe to the standard events with the signatures pattern in Verify webhook signatures — raw body before any JSON parser, X-Orbit-Signature (legacy X-Devotel-Signature fallback), answer 401 on failure. Delivery is at-least-once, so dedupe on the stable envelope id (the Idempotency-Key header mirrors it) — the same event may arrive twice after an ambiguous outcome. Inside the loop, decisions are naturally idempotent too: approving or rejecting an already-decided item returns 404, and a self-approve attempt returns 409 before any state moves. Every queue decision and policy change lands in the audit log: verify.approval.approved, verify.approval.rejected (with the reason), and verify.approval.settings.updated.

Failure modes

Symptom	Cause	Fix
`409 Conflict` on approve	Approver is the requester	A different owner or admin decides; the requester can reject their own item with a reason such as “superseded”.
`403` on queue, decisions, or `PUT /settings`	Role is not owner or admin	An owner elevates the member, or an owner/admin works the queue (`GET /settings` stays readable by any member).
Empty queue after a submission	Gate off, or burst below the threshold	Check the policy; blank or lower `resend_burst_threshold`.
Approved burst did not resend immediately	Approval only opens the gate; dispatch still follows cooldown, rate limits, and channel fallback	Wait for the normal dispatch cycle.
Verification expired in the queue	A queued burst outlived its verification	The replay is declined by normal resend rules — start a fresh verification.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

OTP approvals workflow: run the two-officer gate end to end

OTP approvals workflow

The five-route group

The two-officer workflow

Worked curl across the loop

1. Read the policy (requester)

2. Set the policy (approver)

3. Review the queue (approver)

4a. Commit: approve

4b. Commit: reject

Webhooks and idempotency

Failure modes

See also

​OTP approvals workflow

​The five-route group

​The two-officer workflow

​Worked curl across the loop

​1. Read the policy (requester)

​2. Set the policy (approver)

​3. Review the queue (approver)

​4a. Commit: approve

​4b. Commit: reject

​Webhooks and idempotency

​Failure modes

​See also

OTP approvals workflow

The five-route group

The two-officer workflow

Worked curl across the loop

1. Read the policy (requester)

2. Set the policy (approver)

3. Review the queue (approver)

4a. Commit: approve

4b. Commit: reject

Webhooks and idempotency

Failure modes

See also