v2

latestOpenAPI 3.1.12026-07-2613060964.2 KB

Update Preference Categories

Use this API to set preference categories to be used in workflow or to show on user preference page.

post/v1/{workspace}/preference_category/

Path parameters

workspacestring required

Workspace slug (staging, production, etc.)

Query parameters

commitboolean

Whether to commit changes immediately. Set to true to make changes live, false to save as draft.

commit_messagestring

Optional commit message describing the changes made. Required when commit=true.

Request body

Example request

{
  "root_categories": [
    {
      "sections": [
        {
          "categories": [
            {
              "digest_schedule": {
                "options": [
                  {
                    "time": {
                      "default_value": "00:00"
                    },
                    "dtstart": {
                      "default_value": "2026-06-20T00:00:00Z"
                    }
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  ]
}

Response

Successfully created/updated preference category

$schemastring

JSON schema reference for preference category structure

status'draft' | 'active'

Current status of the preference category

version_nointeger

Version number field as an identifier to track the version

commit_messagestring

Commit message describing the changes that were made

committed_atstring date-time

Timestamp when the changes were committed

Example response

{
  "$schema": "https://schema.suprsend.com/preference_category/v1/schema.json",
  "root_categories": [
    {
      "root_category": "system",
      "sections": [
        {
          "name": "Account Updates",
          "description": "Important account-related notifications",
          "categories": [
            {
              "category": "password-reset",
              "name": "Password Reset",
              "default_preference": "opt_in",
              "default_mandatory_channels": [
                "email"
              ],
              "digest_schedule": {
                "options": [
                  {
                    "time": {
                      "default_value": "00:00"
                    },
                    "dtstart": {
                      "default_value": "2026-06-20T00:00:00Z"
                    }
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  ],
  "status": "draft",
  "version_no": 3,
  "validation_result": {
    "is_valid": true
  }
}