SUsuprsend

Update Preference Categories

Changed on

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

post/v1/{workspace}/preference_category/

Request

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. Used only 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 draft

$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"
              ],
              "is_commercial": true,
              "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
  }
}

Changes

  • 69f49fd5da7cRevision changes
    • info

      added the new optional request property //////

    • info

      added the optional property ////// to the response with the status

  • 5f0169085547Revision changes
    • breaking

      the request property became required

    • breaking

      the request property ////// became required

    • breaking

      the request property ////// became required

    • breaking

      the request property's minItems was increased to 3

    • breaking

      removed the success response with the status

    • warning

      the ////// request property's maxLength was set to 128

    • warning

      the //// request property's maxLength was set to 128

    • info

      the request optional property ////// became read-only

    • info

      added the new ms_teams enum value to the request property ///////

    • info

      added the success response with the status