Update organization settings

Server URLloading...

PATCH

/v1/organization

Send

Authorization

Body

Applies a partial update to your organization. Settable: name, billing_email, message_retention_days, mms_retention_days, is_reseller, and the quiet_hours and auto_replies blocks. Plan, throughput tier, and registration state are managed elsewhere and cannot be changed here. The updated organization is returned in the response.

Enabling acting on behalf of other companies (is_reseller set from false to true) requires a commercial organization; personal-tenant organizations return 422 RESELLER_NOT_ELIGIBLE. Turning it back off (true to false) is rejected with 422 RESELLER_HAS_BRANDS while any brand still exists.

The auto_replies block configures the keyword auto-reply guardrail (STOP / HELP / START confirmations, on by default). Custom reply copy can be set per keyword class (max 320 characters; pass null to return to the platform default). Disabling the guardrail (enabled: false) requires an explicit attestation that your organization will handle HELP and STOP responses itself; omitting it returns 422 ATTESTATION_REQUIRED. Re-enabling needs no attestation. Every change is recorded on your audit log. Disabling auto-replies never affects opt-out handling itself: STOP always suppresses future sends to that contact.

Field semantics:

• name cannot be set to null when present; doing so returns 422 VALIDATION_FAILED.
• billing_email set to explicit null clears the value; omitting the field leaves it unchanged.
• message_retention_days must be an integer in the range [30, 365]; out-of-range values return 422 VALIDATION_FAILED. Windows beyond 365 days require a signed addendum. Lowering the window takes effect on the next retention sweep; raising it does not restore content that has already been removed.

Requires the org:admin:write scope. Issue this scope on a separate key from your sending and read keys so a compromised data-plane key cannot change retention settings.

Response Body

curl -X PATCH "https://example.com/v1/organization" \  -H "Content-Type: application/json" \  -d '{    "name": "Acme Health, Inc."  }'

{
  "success": true,
  "data": {
    "id": "0190a1b2-c3d4-e5f6-a7b8-c9d0e1f2a3b4",
    "name": "Acme Health, Inc.",
    "billing_email": "ap@acme.example",
    "plan": "payg",
    "throughput_tier": 2,
    "message_retention_days": 60,
    "mms_retention_days": 30,
    "is_reseller": false,
    "quiet_hours": {
      "enabled": false,
      "start": "21:00",
      "end": "08:00",
      "mode": "reject"
    },
    "auto_replies": {
      "enabled": true,
      "stop_text": null,
      "help_text": null,
      "start_text": null
    },
    "registration_status": {
      "brand": "ACTIVE",
      "brand_count": 1,
      "campaign_count": 2
    },
    "created_at": "2026-01-04T12:00:00Z"
  }
}

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "authentication failed",
    "request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
  }
}

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "missing required scope",
    "request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
  }
}

{
  "success": false,
  "error": {
    "code": "ATTESTATION_REQUIRED",
    "message": "disabling auto replies requires auto_replies.attestation, an explicit statement that your organization will handle HELP and STOP responses itself",
    "details": {
      "auto_replies.attestation": "required to disable auto replies"
    },
    "request_id": "01JTBQH2FZ8K1RXC0WJ4Z9P3VM"
  }
}