Org settings orientation: read, patch a scope, read the merge

Read → patch → read back

Org configuration lives on one object per organization (the same record GET /api/v1/settings/general and GET /api/v1/settings/organization expose). Scopes — voice, sms, compliance, voice-clones, and the other slices the dashboard groups under Settings — are keys on that object, not separate resources. Every change follows one loop: read the current object, patch the scope you’re changing, then read again to see the merged result. Re-reading before you write is the safest way to learn what’s already set — sibling keys in the same scope are preserved verbatim, so you never have to resend them. Reads are available to any member. Writes are role-gated: most are owner/admin (PUT /api/v1/settings/general), and the stricter ones — consent, marketing, inbox-AI policy, and fraud caps (PATCH/PUT /api/v1/settings/compliance/*) — accept the owner role only. Call a write without the role and you get the standard 403 envelope. Configuration is server-side only here — no message is sent, no call is placed, and no routing changes because a scope changed. An outbound velocity or spend cap constrains your own org’s send path only; it never creates or reroutes an outbound path for another tenant.

1. Read the current object

GET /api/v1/settings/compliance/fraud-caps

Reads return the scope’s full current state — your org’s overrides plus the platform floor each override sits on. An override that was never set comes back null (the floor applies), so the response always carries the complete shape.

{
  "data": {
    "channels": [
      {
        "channel": "sms",
        "max_per_min": 60,
        "max_daily_spend_cents": 20000,
        "floor_per_min": 20,
        "floor_daily_spend_cents": 5000
      },
      {
        "channel": "whatsapp",
        "max_per_min": null,
        "max_daily_spend_cents": null,
        "floor_per_min": 40,
        "floor_daily_spend_cents": 15000
      }
    ],
    "voice": {
      "max_calls_per_min": null,
      "max_daily_spend_cents": null,
      "country_max_per_min": {},
      "floor_calls_per_min": 30,
      "floor_daily_spend_cents": 10000
    }
  },
  "meta": {
    "request_id": "req_caps_read",
    "timestamp": "2026-08-28T09:12:00.000Z"
  }
}

Only sms has overrides; whatsapp and voice ride the platform floor.

2. Patch one scope

PUT /api/v1/settings/compliance/fraud-caps

Send only the scope you’re changing. The write is a merge, not a replace — the sms override from step 1 and every untouched scope survive. A leaf value sets the override; a leaf null clears it back to the platform floor. The response tells you exactly which keys were written (set) and which were removed (cleared). Request

{
  "caps": {
    "whatsapp": {
      "max_per_min": 100,
      "max_daily_spend_cents": 40000
    }
  }
}

{
  "data": {
    "set": {
      "whatsapp": {
        "max_per_min": 100,
        "max_daily_spend_cents": 40000
      }
    },
    "cleared": []
  },
  "meta": {
    "request_id": "req_caps_patch",
    "timestamp": "2026-08-28T09:12:10.000Z"
  }
}

3. Read again — the merged result

GET /api/v1/settings/compliance/fraud-caps

The second read shows the scope you patched next to the overrides you never touched. sms still holds step 1’s values; voice is still at the floor. Nothing else moved.

{
  "data": {
    "channels": [
      {
        "channel": "sms",
        "max_per_min": 60,
        "max_daily_spend_cents": 20000,
        "floor_per_min": 20,
        "floor_daily_spend_cents": 5000
      },
      {
        "channel": "whatsapp",
        "max_per_min": 100,
        "max_daily_spend_cents": 40000,
        "floor_per_min": 40,
        "floor_daily_spend_cents": 15000
      }
    ],
    "voice": {
      "max_calls_per_min": null,
      "max_daily_spend_cents": null,
      "country_max_per_min": {},
      "floor_calls_per_min": 30,
      "floor_daily_spend_cents": 10000
    }
  },
  "meta": {
    "request_id": "req_caps_read_back",
    "timestamp": "2026-08-28T09:12:20.000Z"
  }
}

Validation error envelope

Values outside the documented constraints fail validation — usually a cap below the platform floor or above the documented maximum — and return 422 with a VALIDATION_ERROR envelope before anything is written:

422

{
  "error": {
    "code": "VALIDATION_ERROR",
    "status": 422,
    "message": "caps.whatsapp.max_per_min must be ≥ the platform floor of 40"
  },
  "meta": {
    "request_id": "req_caps_patch_422",
    "timestamp": "2026-08-28T09:12:11.000Z"
  }
}

Nothing was stored — the write is accepted or rejected as a whole, so a scope you offend on never half-applies. Fix the offending value and retry the same request; read back to confirm the merge.

API Reference

All Endpoints

Org settings orientation: read, patch a scope, read the merge

Read → patch → read back

1. Read the current object

2. Patch one scope

3. Read again — the merged result

Validation error envelope

​Read → patch → read back

​1. Read the current object

​2. Patch one scope

​3. Read again — the merged result

​Validation error envelope

Read → patch → read back

1. Read the current object

2. Patch one scope

3. Read again — the merged result

Validation error envelope