Skip to main content
POST
/
v1
/
{workspace}
/
preference_category
Create/Update Category
curl -X POST "https://management-api.suprsend.com/v1/{workspace}/preference_category/?commit=false" \
  --header "Authorization: ServiceToken {token}" \
  --header "Content-Type: application/json" \
  --data '{
    "root_categories": [
      {
        "root_category": "system"
      },
      {
        "root_category": "transactional",
        "sections": [
          {
            "name": "Task Updates",
            "categories": [
              {
                "category": "tagged-to-me",
                "name": "Tagged to Me",
                "description": "Status Update or mentions on tasks assigned by me or tagged to me",
                "default_preference": "opt_in"
              }
            ]
          }
        ]
      },
      {
        "root_category": "promotional",
        "sections": [
          {
            "name": "Product Updates",
            "categories": [
              {
                "category": "newsletter",
                "name": "Newsletter",
                "default_preference": "opt_out"
              }
            ]
          }
        ]
      }
    ]
  }'
{
  "$schema": "https://schema.suprsend.com/preference_category/v1/schema.json",
  "root_categories": [
    {
      "root_category": "system",
      "sections": []
    },
    {
      "root_category": "transactional",
      "sections": [
        {
          "name": "Task Updates",
          "description": null,
          "tags": null,
          "categories": [
            {
              "category": "tagged-to-me",
              "name": "Tagged to Me",
              "description": "Status Update or mentions on tasks assigned by me or tagged to me",
              "default_preference": "opt_in",
              "default_mandatory_channels": null,
              "default_opt_in_channels": null,
              "tags": null
            }
          ]
        }
      ]
    },
    {
      "root_category": "promotional",
      "sections": [
        {
          "name": "Product Updates",
          "description": null,
          "tags": null,
          "categories": [
            {
              "category": "newsletter",
              "name": "Newsletter",
              "description": null,
              "default_preference": "opt_out",
              "default_mandatory_channels": null,
              "default_opt_in_channels": null,
              "tags": null
            }
          ]
        }
      ]
    }
  ],
  "version_no": 3,
  "status": "draft",
  "commit_message": null,
  "committed_at": null,
  "validation_result": {
    "is_valid": true
  }
}
⚠️ This API call will override existing categories with whatever is passed in the request body. Recommended approach is to first fetch the current categories using GET method, modify the response as needed, and then send it back in the request body.
You can read more about preference categories here.

Note: Changes will only be pushed if "validation_result":{"is_valid":true} in the response. General reasons for validation failure are:

  • There are multiple categories with the same slug
  • Some subcategories have been deleted in this version, on which active workflows are configured
  • You’ve not passed all three categories in the request body - system, transactional, promotional

Authorizations

​
ServiceToken <token>
string
header
required

You can get Service Token from SuprSend dashboard -> Account Settings -> Service Tokens section.

Path Parameters

​
workspace
string
required

Workspace slug (staging, production, etc.)

Query Parameters

​
commit
boolean

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

​
commit_message
string

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

Body

application/json
​
root_categories
object[]

Array of root preference categories. Include all three root categories (system, transactional, promotional) even if empty.

Response

Successfully created/updated preference category

​
$schema
string

JSON schema reference for preference category structure

Example:

"https://schema.suprsend.com/preference_category/v1/schema.json"

​
root_categories
object[]

Array of root preference categories

​
status
enum<string>

Current status of the preference category

Available options:
draft,
active
Example:

"draft"

​
version_no
integer

Version number of the preference category

Example:

3

​
commit_message
string

Commit message describing the changes that were made

Example:

null

​
committed_at
string<date-time>

Timestamp when the changes were committed

Example:

null

​
validation_result
object

Result of validating the preference category