> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suprsend.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create or Update Preference Category
> Use this API to set preference categories to be used in workflow or to show on user preference page.
⚠️ 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](/reference/get-category), modify the response as needed, and then send it back in the request body.
You can read more about preference categories [here](/docs/notification-category).
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
## OpenAPI
````yaml POST /v1/{workspace}/preference_category/
openapi: 3.1.1
info:
title: SuprSend API
description: APIs supported on suprsend platform
version: 1.2.2
servers:
- url: https://hub.suprsend.com
security:
- sec0: []
- BearerAuth: []
paths:
/v1/{workspace}/preference_category/:
post:
summary: Update Preference Categories
description: >-
Use this API to set preference categories to be used in workflow or to
show on user preference page.
operationId: create-update-category
parameters:
- in: path
name: workspace
required: true
schema:
type: string
description: Workspace slug (staging, production, etc.)
- in: query
name: commit
schema:
type: boolean
description: >-
Whether to commit changes immediately. Set to true to make changes
live, false to save as draft.
- in: query
name: commit_message
schema:
type: string
description: >-
Optional commit message describing the changes made. Required when
commit=true.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
root_categories:
type: array
description: >-
Array of root preference categories. Include all three root
categories (system, transactional, promotional) even if
empty.
items:
type: object
properties:
root_category:
type: string
description: >-
Root category classification. system=critical
notifications, transactional=user actions,
promotional=marketing.
enum:
- system
- transactional
- promotional
sections:
type: array
description: >-
Sections group related categories. Users cannot set
preferences at section level.
items:
type: object
properties:
name:
type: string
description: >-
Name of the section displayed in the preference
interface.
description:
type: string
description: >-
Description of what notifications this section
covers.
tags:
type: array
description: >-
Tags to organize and filter sections. Use
lowercase, hyphenated values (e.g., "security",
"billing").
items:
type: string
categories:
type: array
description: Categories that users can set preferences for.
items:
type: object
properties:
category:
type: string
description: >-
Unique identifier for the category. Use
lowercase letters, numbers, and hyphens
only.
pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
name:
type: string
description: >-
Display name for the category shown in the
preference interface.
description:
type: string
description: >-
Description of what notifications this
category covers.
default_preference:
type: string
description: >-
Default preference setting for this
category.
enum:
- opt_in
- opt_out
- cant_unsubscribe
default_mandatory_channels:
type: array
description: >-
Channels that users cannot unsubscribe
from when default preference is
cant_unsubscribe.
items:
type: string
enum:
- email
- sms
- whatsapp
- androidpush
- inbox
- iospush
- slack
- webpush
default_opt_in_channels:
type: array
nullable: true
description: >-
Add channels that should be opted-in by
default when preference is either `On` or
`Can't Unsubscribe`. Set to null or do not
pass this parameter to set all channels as
opted-in. In case of `Can't Unsubscribe`,
mandatory channels are opted-in by
default.
items:
type: string
enum:
- email
- sms
- whatsapp
- androidpush
- inbox
- iospush
- slack
- webpush
- ms_teams
tags:
type: array
description: >-
Tags to organize and filter categories.
Use lowercase, hyphenated values (e.g.,
"user-management", "payment-alerts").
items:
type: string
pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
responses:
'200':
description: Successfully created/updated preference category
content:
application/json:
schema:
type: object
properties:
$schema:
type: string
description: JSON schema reference for preference category structure
example: >-
https://schema.suprsend.com/preference_category/v1/schema.json
root_categories:
type: array
description: Array of root preference categories
items:
type: object
properties:
root_category:
type: string
description: >-
The root category classification for the preference
category
example: system
sections:
type: array
description: Array of sections within the preference category
items:
type: object
properties:
name:
type: string
description: Name of the section
example: Account Updates
categories:
type: array
description: Array of categories within this section
items:
type: object
properties:
category:
type: string
description: Unique identifier for the category
example: password-reset
name:
type: string
description: Display name for the category
example: Password Reset
default_preference:
type: string
description: >-
Default preference setting for this
category
example: opt_in
default_mandatory_channels:
type: array
description: >-
Channels that are mandatory for this
category
items:
type: string
example:
- email
default_opt_in_channels:
type: array
nullable: true
description: >-
Channels that are included in the
default "On" state when default
preference is opt_in
items:
type: string
example: null
status:
type: string
description: Current status of the preference category
enum:
- draft
- active
example: draft
version_no:
type: integer
description: Version number of the preference category
example: 3
commit_message:
type: string
description: Commit message describing the changes that were made
example: null
committed_at:
type: string
format: date-time
description: Timestamp when the changes were committed
example: null
validation_result:
type: object
description: Result of validating the preference category
properties:
is_valid:
type: boolean
description: >-
true if the preference category is valid, false if
there are errors
example: true
errors:
type: array
description: Array of error messages when validation fails
items:
type: string
example:
$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
'401':
description: ServiceToken not found
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 401
message:
type: string
example: ServiceToken not found
example:
code: 401
message: ServiceToken not found
'404':
description: Workspace not found
content:
application/json:
schema:
type: object
properties:
code:
type: integer
example: 404
message:
type: string
example: 'workspace not found for slug/uid: workspace'
example:
code: 404
message: 'workspace not found for slug/uid: workspace'
security:
- ServiceTokenAuth: []
servers:
- url: https://management-api.suprsend.com
x-codeSamples:
- lang: cURL
label: Create/Update Category
source: >
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"
}
]
}
]
}
]
}'
components:
securitySchemes:
sec0:
type: apiKey
in: header
name: Authorization
x-bearer-format: bearer
description: >-
Bearer authentication header of the form `Bearer `, where
is your auth token.
BearerAuth:
type: http
scheme: bearer
bearerFormat: API_Key
description: >-
Pass as `Bearer `. Get API Key from SuprSend dashboard
Developers -> API Keys section.
ServiceTokenAuth:
type: apiKey
in: header
name: ServiceToken
description: >-
You can get Service Token from [SuprSend dashboard -> Account Settings
-> Service
Tokens](https://app.suprsend.com/en/account-settings/service-tokens)
section.
````