openapi: 3.1.1 info: title: SuprSend Broadcast User API description: APIs supported on suprsend platform version: 1.2.2 servers: - url: https://hub.suprsend.com security: - sec0: [] - BearerAuth: [] tags: - name: User paths: /v1/user/{distinct_id}/preference/category/: get: summary: All Categories security: - BearerAuth: [] description: API to fetch user preferences across all categories. operationId: get-user-preference-all-categories parameters: - name: distinct_id in: path description: distinct_id of the user whose preferences should be fetched schema: type: string required: true - name: tenant_id in: query description: to fetch user preferences for a particular tenant schema: type: string - name: show_opt_out_channels in: query description: set this flag to `true` if you want to fetch channel list for opt-out categories. schema: type: boolean default: false - name: tags in: query description: 'Filter preference categories with tags assigned to them. Used to filter preference categories relevant to the user on UI based on their roles, department or teams. You can apply single tag filter like `tags=tag1` or build nested conditions using logical operators - `and`, `or`, `not`, `exists`. Example: ``` tags=admin tags={"or":[{"and":["admin","sales"]},{"and":["admin","manager"]}]} tags={"not":"admin"} tags={"exists":true} ' schema: type: string - name: locale in: query description: "Locale code (e.g., `es`, `fr`, `de`, `ja`, `es-AR`) to fetch preference translations in user's locale. When provided, the API looks for category and section names and descriptions in the respective locale file. \nIf a translation is missing for the requested locale, the system automatically falls back in this order: `locale-region` (e.g., `es-AR`) → `locale` (e.g., `es`) → `en` (English - always available).\n" schema: type: string example: es responses: '200': description: '200' content: application/json: examples: Result: value: meta: count: 12 limit: 10 offset: 0 results: - name: Newsletter category: newsletter description: Send me updates on new product updates original_preference: null preference: opt_in is_editable: false channels: - channel: email preference: opt_in is_editable: false - channel: ms_teams preference: opt_in is_editable: false schema: type: object properties: meta: type: object properties: count: type: integer example: 12 limit: type: integer example: 10 offset: type: integer example: 0 results: type: array items: type: object properties: name: type: string example: Newsletter category: type: string example: newsletter description: type: string example: Send me updates on new product updates original_preference: type: string description: default preference of the category nullable: true example: null preference: type: string enum: - opt_in - opt_out example: opt_in description: updated user preference of the category is_editable: type: boolean description: false when category default preference is set to `can't unsubscribe` example: false channels: type: array description: channel level preference in the category items: type: object properties: channel: type: string description: channel name example: email preference: type: string description: user preference for this channel (opt_in, opt_out) example: opt_in is_editable: type: boolean description: whether the user can edit this channel preference example: false '404': description: 404 - Not Found content: application/json: examples: Result: value: code: 404 message: 'user [distinct_id: ''user1''] not found' schema: type: object properties: code: type: integer example: 404 message: type: string example: 'user [distinct_id: ''user1''] not found' deprecated: false tags: - User /v1/user/{distinct_id}/preference/channel_preference/: get: summary: All Channels security: - BearerAuth: [] description: API to retrieve user preferences for all channels. operationId: get-user-preference-channel parameters: - name: distinct_id in: path description: distinct_id of the user whose preferences should be fetched schema: type: string required: true - name: tenant_id in: query description: to fetch user preferences for a particular tenant schema: type: string responses: '200': description: '200' content: application/json: examples: Result: value: channel_preferences: - channel: androidpush is_restricted: false - channel: email is_restricted: false schema: type: object properties: channel_preferences: type: array items: type: object properties: channel: type: string description: channel name example: androidpush is_restricted: type: boolean description: True means notification will be sent in categories where this channel is marked as mandatory channel. False means opt_in on channel. '404': description: 404 - Not Found content: application/json: examples: Result: value: code: 404 message: 'user [distinct_id: ''user1''] not found' schema: type: object properties: code: type: integer example: 404 message: type: string example: 'user [distinct_id: ''user1''] not found' deprecated: false tags: - User patch: summary: Overall Channel level security: - BearerAuth: [] description: API to update user preferences across all channels. operationId: update-user-preference-channel parameters: - name: distinct_id in: path description: distinct_id of the user whose preferences should be fetched schema: type: string required: true - name: tenant_id in: query description: to fetch user preferences for a particular tenant schema: type: string requestBody: content: application/json: schema: type: object properties: channel_preferences: type: array description: Use this to update channel level user preferences. Set `is_restricted - true` if the channel is opted_out by the user. This will only send critical notifications to the user which can't be opted out items: properties: channel: type: string description: Add channel as `email`, `inbox`, `sms`, `whatsapp`, `androidpush`, `slack`, `iospush`, `webpush` default: email is_restricted: type: boolean description: set `is_restricted = true` if user wants to receive notification in mandatory categories on this channel. Mandatory categories are `can't unsubscribe` categories and the above channel is added as `mandatory channel` in that category default: false type: object responses: '202': description: '202' content: application/json: examples: Result: value: channel_preferences: - channel: email is_restricted: true - channel: inbox is_restricted: false schema: type: object properties: channel_preferences: type: array items: type: object properties: channel: type: string example: email is_restricted: type: boolean example: 'true' '400': description: 400 - Bad Request content: application/json: examples: Result: value: code: 400 detail: channel_preferences[0].channel: must be one of ["sms", "email", "androidpush" "iospush", "webpush", "inbox", "whatsapp", "slack", "ms_teams"] message: '{"channel_preferences[0].channel": must be one of ["sms", "email", "androidpush" "iospush", "webpush", "inbox", "whatsapp", "slack", "ms_teams"]' schema: type: object properties: code: type: integer example: 400 detail: type: object description: error details message: type: string description: error message deprecated: false tags: - User /v1/user/{distinct_id}/preference/category/{category_slug}/: patch: summary: Category and Channel within Category security: - BearerAuth: [] description: API to update user preferences for a specific notification category. operationId: update-user-preference-category x-codeSamples: - lang: cURL label: Update User Category Preference - Opt Out Channel source: "curl -X PATCH \"https://hub.suprsend.com/v1/user/user123/preference/status-update-alert/\" \\\n --header 'Authorization: Bearer __YOUR_API_KEY__' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"preference\": \"opt_in\",\n \"opt_out_channels\": [\"email\", \"slack\"]\n }'\n" parameters: - name: distinct_id in: path description: distinct_id of the user whose preferences should be fetched schema: type: string required: true - name: tenant_id in: query description: to fetch user preferences for a particular tenant schema: type: string - name: category_slug in: path description: notification category slug. You can get this from Notification Categories page on SuprSend dashboard -> Settings page schema: type: string required: true - name: locale in: query description: 'Locale code (e.g., `es`, `fr`, `de`, `ja`, `es-AR`) to fetch translated category and section names and descriptions. When provided, the API returns category and section names and descriptions in the specified language if translations are available. If a translation is missing for the requested locale, the system automatically falls back in this order: `locale-region` (e.g., `es-AR`) → `locale` (e.g., `es`) → `en` (English - always available). ' schema: type: string example: es requestBody: content: application/json: schema: type: object properties: preference: type: string description: 'choose one of the options: `opt_in` if the user has allowed notification in this category and `opt_out` if user wants to discontinue notification in this category' default: opt_in opt_out_channels: type: array description: Add array of channels if user wants to unsubscribe from particular channels in this category. Add channels as `email`, `sms`, `whatsapp`, `androidpush`, `inbox`, `iospush`, `slack`, `webpush` items: type: string opt_in_channels: type: array description: You can either pass opt_out_channels when user opts out from a channel in the category or opt_in_channels when user opts in to a channel in the category. Add channels as `email`, `sms`, `whatsapp`, `androidpush`, `inbox`, `iospush`, `slack`, `webpush` items: type: string responses: '202': description: '202' content: application/json: examples: Result: value: name: Status Update Alert category: status-update-alert description: Send me updates when account status changes original_preference: opt_in preference: opt_in is_editable: true channels: - channel: email preference: opt_in is_editable: true - channel: ms_teams preference: opt_in is_editable: true - channel: slack preference: opt_in is_editable: true schema: type: object properties: name: type: string example: Status Update Alert category: type: string example: status-update-alert description: type: string example: Send me updates when account status changes original_preference: type: string description: default preference of the category example: opt_in preference: type: string description: final user preference of the category example: opt_in is_editable: type: boolean description: false for categories where default preference is set to can't unsubscribe example: true channels: type: array items: type: object properties: channel: type: string example: email preference: type: string enum: - opt_in - opt_out example: opt_in is_editable: type: boolean example: true '404': description: 404 - Not Found content: application/json: examples: Result: value: code: 404 message: category '_category_slug_' not found schema: type: object description: error code and message detailing the error deprecated: false tags: - User get: summary: Single Category security: - BearerAuth: [] description: API to fetch user preferences for a given category. operationId: get-user-preferences-single-category parameters: - name: distinct_id in: path description: distinct_id of the user whose preferences should be fetched schema: type: string required: true - name: tenant_id in: query description: to fetch user preferences for a particular tenant schema: type: string - name: category_slug in: path description: notification category slug. You can get this from Notification Categories page on SuprSend dashboard -> Settings page schema: type: string required: true - name: show_opt_out_channels in: query description: set this flag to `true` if you want to fetch channel list for opt-out categories. schema: type: boolean default: false - name: locale in: query description: 'Locale code (e.g., `es`, `fr`, `de`, `ja`, `es-AR`) to fetch preference translations in user''s locale. When provided, the API looks for category and section names and descriptions in the respective locale file. If a translation is missing for the requested locale, the system automatically falls back in this order: `locale-region` (e.g., `es-AR`) → `locale` (e.g., `es`) → `en` (English - always available). ' schema: type: string example: es responses: '200': description: '200' content: application/json: examples: Result: value: name: Newsletter category: newsletter description: Send me updates on new product updates original_preference: null preference: opt_in is_editable: false channels: - channel: email preference: opt_in is_editable: false - channel: ms_teams preference: opt_in is_editable: false schema: type: object properties: name: type: string description: name of the notification category example: Newsletter category: type: string description: category slug identifier example: newsletter description: type: string description: description of the notification category example: Send me updates on new product updates original_preference: type: string description: default preference of the category nullable: true example: null preference: type: string description: updated user preference of the category example: opt_in is_editable: type: boolean description: false when category default preference is set to `can't unsubscribe` example: false channels: type: array description: channel level preference in the category items: type: object properties: channel: type: string description: channel name example: email preference: type: string description: user preference for this channel (opt_in, opt_out) example: opt_in is_editable: type: boolean description: whether the user can edit this channel preference example: false '404': description: 404 - Not Found content: application/json: examples: Result: value: code: 404 message: category 'category_slug' not found schema: type: object properties: code: type: integer example: 404 message: type: string example: category 'category_slug' not found deprecated: true tags: - User /v1/user/{distinct_id}/preference/: get: summary: Full Preference security: - BearerAuth: [] description: API to fetch user preferences across all channels and categories. operationId: get-user-full-preference parameters: - name: distinct_id in: path description: distinct_id of the user whose preferences should be fetched schema: type: string required: true - name: tenant_id in: query description: to fetch user preferences for a particular tenant schema: type: string - name: show_opt_out_channels in: query description: set this flag to `true` if you want to fetch channel list for opt-out categories. schema: type: boolean default: false - name: tags in: query description: 'Filter preference categories with tags assigned to them. Used to filter preference categories relevant to the user on UI based on their roles, department or teams. You can apply single tag filter like `tags=tag1` or build nested conditions using logical operators - `and`, `or`, `not`, `exists`. Example: ``` tags=admin tags={"or":[{"and":["admin","sales"]},{"and":["admin","manager"]}]} tags={"not":"admin"} tags={"exists":true} ' schema: type: string - name: locale in: query description: 'Locale code (e.g., `es`, `fr`, `es-AR`) to fetch preference translations in user''s locale. When provided, the API looks for category and section names and descriptions in the respective locale file. If a translation is missing for the requested locale, the system automatically falls back in this order: `locale-region` (e.g., `es-AR`) → `locale` (e.g., `es`) → `en` (English - always available). ' schema: type: string example: es responses: '200': description: '200' content: application/json: examples: Result: value: sections: - subcategories: - name: Newsletter category: newsletter description: Send me updates on new product updates preference: opt_in is_editable: true channels: - channel: androidpush preference: opt_in is_editable: true - channel: email preference: opt_in is_editable: true channel_preferences: - channel: email is_restricted: false schema: type: object properties: sections: type: array items: type: object properties: subcategories: type: array items: type: object properties: name: type: string example: Newsletter category: type: string example: newsletter description: type: string example: Send me updates on new product updates preference: type: string enum: - opt_in - opt_out example: opt_in is_editable: type: boolean description: false when category default preference is set to can't unsubscribe channels: type: array items: type: object properties: channel: type: string example: email preference: type: string enum: - opt_in - opt_out example: opt_in is_editable: type: boolean description: false when category default preference is set to can't unsubscribe channel_preferences: type: array items: type: object properties: channel: type: string description: channel name example: androidpush is_restricted: type: boolean description: True means notification will be sent in categories where this channel is marked as mandatory channel. False means opt_in on channel. '404': description: '404' content: application/json: examples: Result: value: code: 404 message: 'user [distinct_id: ''user1''] not found' schema: type: object properties: code: type: integer example: 404 message: type: string example: 'user [distinct_id: ''user1''] not found' deprecated: false tags: - User patch: summary: Update User Full Preference security: - BearerAuth: [] description: API to update user preferences across all channels and categories with translated names and descriptions in the response. operationId: update-user-full-preference parameters: - name: distinct_id in: path description: distinct_id of the user whose preferences should be updated schema: type: string required: true - name: tenant_id in: query description: to update user preferences for a particular tenant schema: type: string requestBody: content: application/json: schema: type: object properties: channel_preferences: type: array description: Use this to update channel level user preferences. Set `is_restricted - true` if the channel is opted_out by the user. This will only send critical notifications to the user which can't be opted out items: type: object properties: channel: type: string description: Add channel as `email`, `inbox`, `sms`, `whatsapp`, `androidpush`, `slack`, `iospush`, `webpush` is_restricted: type: boolean description: set `is_restricted = true` if user wants to receive notification in mandatory categories on this channel. Mandatory categories are `can't unsubscribe` categories and the above channel is added as `mandatory channel` in that category categories: type: array description: Use this to update user preference across categories and channels inside a category. items: type: object properties: category: type: string description: notification category slug preference: type: string enum: - opt_in - opt_out description: set `opt_in` to turn on notifications on all or selected channels, `opt_out` to turn-off notifications opt_out_channels: type: array description: List of channels to opt-out from this category. Only applicable when preference is `opt_in` items: type: string opt_in_channels: type: array description: List of channels to opt-in for this category. Only applicable when preference is `opt_in` items: type: string examples: Update Preferences: value: channel_preferences: - channel: email is_restricted: false categories: - category: _category_slug_ preference: opt_in opt_out_channels: [] opt_in_channels: [] responses: '200': description: '200' content: application/json: examples: Result: value: sections: - name: null slug: null subcategories: - name: Promotion de remboursement category: refund-promotion description: mises à jour original_preference: null preference: opt_in is_editable: false channels: - channel: email preference: opt_in is_editable: false - channel: inbox preference: opt_in is_editable: false channel_preferences: - channel: email is_restricted: false - channel: inbox is_restricted: false schema: type: object properties: sections: type: array items: type: object properties: name: type: string nullable: true slug: type: string nullable: true description: type: string nullable: true tags: type: array nullable: true items: type: string subcategories: type: array items: type: object properties: name: type: string category: type: string description: type: string nullable: true tags: type: array nullable: true items: type: string effective_tags: type: array nullable: true items: type: string original_preference: type: string nullable: true enum: - opt_in - opt_out - cant_unsubscribe preference: type: string enum: - opt_in - opt_out - cant_unsubscribe is_editable: type: boolean channels: type: array items: type: object properties: channel: type: string preference: type: string enum: - opt_in - opt_out is_editable: type: boolean channel_preferences: type: array items: type: object properties: channel: type: string is_restricted: type: boolean '404': description: '404' content: application/json: examples: Result: value: code: 404 message: 'user [distinct_id: ''user1''] not found' schema: type: object properties: code: type: integer example: 404 message: type: string example: 'user [distinct_id: ''user1''] not found' deprecated: false tags: - User /v1/user/{distinct_id}/: post: summary: Create / Update Users security: - BearerAuth: [] description: API to upsert (create if not exists, update if exists) user profile using a `distinct_id`. operationId: create-update-users x-codeSamples: - lang: cURL source: "curl -X POST \"https://hub.suprsend.com/v1/user/user123/\" \\\n --header 'Authorization: Bearer __YOUR_API_KEY__' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"$email\": [\"user@example.com\"],\n \"$sms\": [\"+1234567890\"],\n \"$slack\": [{\n \"email_id\": \"user@example.com\",\n \"access_token\": \"xoxb-...\"\n }],\n \"$ms_teams\": [{\n \"user_id\": \"teams_user_id_12345\",\n \"tenant_id\": \"tenant_12345\",\n \"service_url\": \"https://smba.trafficmanager.net/amer\"\n }]\n }'\n" parameters: - name: distinct_id in: path description: Unique identifier of the user in your system schema: type: string required: true requestBody: content: application/json: example: $email: - jsmith@example.com $sms: - '+1234567890' $whatsapp: - '+1234567890' $inbox: - 4nlPk4XXLcDxxxHQ70xx2Cx24 $webpush: - token: webpush_token_abc123 endpoint: https://fcm.googleapis.com/fcm/send/abc123 keys: p256dh: BNJxwH... auth: tBH... $androidpush: - android_push_token_xyz987 $iospush: - ios_push_token_lmn456 $slack: - user_id: U01ABCDE2F3 team_id: T1234567890 access_token: xoxb-... $ms_teams: - user_id: teams_user_id_12345 tenant_id: tenant_12345 conversation_id: conversation_12345 $timezone: America/New_York $locale: en_GB custom_key: custom_value schema: type: object properties: $email: type: array items: type: string format: email description: List of email addresses. You can add other channels in the same format by replacing `$email` with the respective channel keys. Supported keys- `$email`, `$sms`, `$whatsapp`, `$inbox`, `$webpush`, `$androidpush`, `$iospush`, `$slack`, `$ms_teams`. $sms: type: array items: type: string description: List of phone numbers for SMS $whatsapp: type: array items: type: string description: List of phone numbers for WhatsApp $inbox: type: array items: type: string description: List of inbox identifiers $androidpush: type: array items: type: string description: List of Android Push tokens $iospush: type: array items: type: string description: List of iOS Push tokens $slack: type: array description: Slack channel configuration items: oneOf: - type: object title: Slack using email required: - email - access_token properties: email: type: string format: email description: User email address example: user@example.com access_token: type: string description: Slack bot access token example: xoxb-XXXXXXXX - type: object title: Slack using member ID required: - user_id - access_token properties: user_id: type: string description: Slack user ID (U/WXXXXXXXX format) example: U/WXXXXXXXX access_token: type: string description: Slack bot access token example: xoxb-XXXXXX - type: object title: Slack using channel required: - channel - access_token properties: channel: type: string description: Slack channel ID (CXXXXXXXX format) example: CXXXXXXXX access_token: type: string description: Slack bot access token example: xoxb-XXXXXX - type: object title: Slack using incoming webhook required: - incoming_webhook properties: incoming_webhook: type: object required: - url properties: url: type: string format: uri description: Slack incoming webhook URL example: https://hooks.slack.com/services/TXXXX/BXXXX/XXXXXXX $ms_teams: type: array description: Microsoft Teams channel configuration items: oneOf: - type: object title: MS Teams using conversation ID required: - tenant_id - service_url - conversation_id properties: tenant_id: type: string description: Microsoft Teams tenant ID example: c1981ab2-9aaf-xxxx-xxxx service_url: type: string format: uri description: Microsoft Teams service URL example: https://smba.trafficmanager.net/amer conversation_id: type: string description: Microsoft Teams conversation ID example: 19:c1524d7c-a06f-456f-8abe-xxxx - type: object title: MS Teams using user ID required: - tenant_id - service_url - user_id properties: tenant_id: type: string description: Microsoft Teams tenant ID example: c1981ab2-9aaf-xxxx-xxxx service_url: type: string format: uri description: Microsoft Teams service URL example: https://smba.trafficmanager.net/amer user_id: type: string description: Microsoft Teams user ID example: 29:1nsLcmJ2RKtYH6Cxxxx-xxxx - type: object title: MS Teams using incoming webhook required: - incoming_webhook properties: incoming_webhook: type: object required: - url properties: url: type: string format: uri description: Microsoft Teams incoming webhook URL example: https://wnk1z.webhook.office.com/webhookb2/XXXXXXXXX $timezone: type: string description: User's timezone in [IANA format](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones#List) example: America/New_York $locale: type: string description: User's locale for [translating](https://suprsend.com/docs/translations) template content in SuprSend. example: en_GB additionalProperties: type: string description: Add any additional property in key-value pair example: val responses: '201': description: '201' content: application/json: examples: Result: value: distinct_id: _distinct_id_ properties: $locale: en_GB $timezone: America/New_York created_at: '2025-04-04T21:37:36.712496+00:00' updated_at: '2025-04-04T21:37:36.743167+00:00' $email: - value: john@example.com status: active perma_status: active $inbox: - value: 4nlPk4t4kurG5kChOELB8Q1LcDI9DHzHQ70st2E2C24 id_provider: suprsend status: active perma_status: active $sms: - value: '+1234567890' status: active perma_status: active $slack: - value: email_id: user@example.com access_token: xoxb-... status: active perma_status: active $ms_teams: - value: user_id: teams_user_id_12345 tenant_id: tenant_12345 service_url: https://smba.trafficmanager.net/amer status: active perma_status: active schema: type: object properties: distinct_id: type: string description: Unique identifier of the user. example: _distinct_id_ properties: type: object description: all user properties in key-value pair. SuprSend reserved properties start with $ created_at: type: string format: date-time description: Timestamp when the user was created. example: 2025-04-04 09:55:12.397856+00:00 updated_at: type: string format: date-time description: Timestamp when the user was last updated. example: 2025-04-04 09:55:12.422388+00:00 $: type: array description: List of active communication channels for the user. items: type: object properties: value: type: string description: channel value status: type: string description: Current status of the channel (active or inactive). example: active perma_status: type: string description: active/disabled. Perma_status is marked disabled in case of hard bounce on the channel. '400': description: '400' content: application/json: examples: Result: value: code: 400 message: invalid_request_error schema: type: object properties: code: type: integer description: HTTP status code indicating the error. message: type: string description: Description of the error type. deprecated: false tags: - User get: summary: Fetch User by id security: - BearerAuth: [] description: API to fetch user object by passing it's unique `distinct_id`. operationId: fetch-user-profile parameters: - name: distinct_id in: path description: Unique identifier of the user in your system schema: type: string required: true responses: '200': description: '200' content: application/json: examples: Result: value: distinct_id: _distinct_id_ properties: $locale: en_GB $timezone: America/New_York created_at: '2025-04-04T21:37:36.712496+00:00' updated_at: '2025-04-04T21:37:36.743167+00:00' $email: - value: john@example.com status: active perma_status: active $inbox: - value: 4nlPk4t4kurG5kChOELB8Q1LcDI9DHzHQ70st2E2C24 id_provider: suprsend status: active perma_status: active schema: type: object properties: distinct_id: type: string description: Unique identifier of the user. example: _distinct_id_ properties: type: object description: all user properties in key-value pair. SuprSend reserved properties start with $ created_at: type: string format: date-time description: Timestamp when the user was created. example: 2025-04-04 09:55:12.397856+00:00 updated_at: type: string format: date-time description: Timestamp when the user was last updated. example: 2025-04-04 09:55:12.422388+00:00 $: type: array description: List of active communication channels for the user. items: type: object properties: value: type: string description: channel value status: type: string description: Current status of the channel (active or inactive). example: active perma_status: type: string description: active/disabled. Perma_status is marked disabled in case of hard bounce on the channel. '400': description: '400' content: application/json: examples: Result: value: code: 400 message: invalid_request_error schema: type: object properties: code: type: integer description: HTTP status code indicating the error. message: type: string description: Description of the error type. deprecated: false tags: - User delete: summary: Delete user security: - BearerAuth: [] description: API to permanently delete a user from SuprSend by passing `distinct_id`. operationId: delete-user parameters: - name: distinct_id in: path description: Unique identifier of the user in your system schema: type: string required: true responses: '204': description: 204 - No Content '404': description: '404' content: application/json: examples: Result: value: code: 404 message: 'user [distinct_id: ''user1''] not found' schema: type: object properties: code: type: integer description: HTTP status code indicating the error. example: 404 message: type: string description: Description of the error. example: 'user [distinct_id: ''user1''] not found' deprecated: false tags: - User patch: summary: Edit User Profile security: - BearerAuth: [] description: API to edit (add/remove) properties and communication-channels for a user. operationId: edit-user-profile x-codeSamples: - lang: cURL label: Edit User Profile source: "curl -X PATCH \"https://hub.suprsend.com/v1/user/user123/\" \\\n --header 'Authorization: Bearer __YOUR_API_KEY__' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"operations\": [\n {\n \"$set\": {\n \"name\": \"John Doe\",\n \"$locale\": \"en_GB\",\n \"$timezone\": \"America/New_York\"\n }\n },\n {\n \"$append\": {\n \"$email\": \"john@example.com\"\n }\n }\n ]\n }'\n" parameters: - name: distinct_id in: path description: unique identifier of the user required: true schema: type: string requestBody: content: application/json: schema: type: object properties: operations: type: array description: 'You can use the following operations to edit user profile. - `$set` to add/update a property - `$unset` to delete property/channel - `$append` to insert values in property/channel array - `$remove` to remove values from property/channel array - `$set_once` to remove immutable properties - `$increment` to increase/decrease integer values on further update ' items: type: object properties: $set: type: object description: 'Use this to set user properties like name, location, locale, etc. Example: `{"name":"Marge Simpson","$locale":"en_GB","$timezone":"America/New_York"}` ' additionalProperties: type: string $unset: type: array description: 'Use this to delete channels or properties from user profile. Channels: `$email`, `$sms`, `$whatsapp`, `$androidpush`, `$iospush`, `$slack`, `$webpush`, `$ms_teams` Example: `["$sms", "$whatsapp", "name"]` ' items: type: string $append: type: object description: 'Use this to add communication channels or update array properties in user profile. Available channel keys: `$email`, `$sms`, `$whatsapp`, `$androidpush`, `$iospush`, `$slack`, `$webpush`, `$ms_teams` Example: `{"$email":"user@example.com"}` ' additionalProperties: type: string $remove: type: object description: 'Use this to remove communication channels or remove values from an array in user profile. Available channel keys: `$email`, `$sms`, `$whatsapp`, `$androidpush`, `$iospush`, `$slack`, `$webpush`, `$ms_teams` Example: `{"$email":"user@example.com"}` ' additionalProperties: type: string $set_once: type: object description: 'Use this to set properties which are not set once and not changed on further updates. Example: `{"first_login_at":"2025-01-01T14:00:00Z"}` ' additionalProperties: type: string $increment: type: object description: 'Use this to increase / decrease integer values on further updates Example: `{"login_count":1}` ' additionalProperties: type: string responses: '202': description: '202' content: application/json: examples: Result: value: distinct_id: _distinct_id_ properties: name: Marge Simpson $locale: en_GB $timezone: America/New_York created_at: '2025-04-04T21:37:36.712496+00:00' updated_at: '2025-04-04T21:37:36.743167+00:00' $email: - value: john@example.com status: active perma_status: active $inbox: - value: 4nlPk4t4kurG5kChOELB8Q1LcDI9DHzHQ70st2E2C24 id_provider: suprsend status: active perma_status: active schema: type: object properties: distinct_id: type: string description: Unique identifier of the user. example: _distinct_id_ properties: type: object description: all user properties in key-value pair. SuprSend reserved properties start with $ created_at: type: string format: date-time description: Timestamp when the user was created. example: 2025-04-04 09:55:12.397856+00:00 updated_at: type: string format: date-time description: Timestamp when the user was last updated. example: 2025-04-04 09:55:12.422388+00:00 $: type: array description: list of all active channels. items: type: object properties: value: type: string description: channel value status: type: string description: Current status of the channel (active or inactive). example: active perma_status: type: string description: active/disabled. Perma_status is marked disabled in case of hard bounce on the channel. deprecated: false tags: - User /v1/user/: get: summary: List Users security: - BearerAuth: [] description: API to list cursor-based paginated list of users in your workspace. operationId: list-users responses: '200': description: '200' content: application/json: examples: Result: value: meta: count: 1201709 limit: 10 has_prev: false before: null has_next: true after: 01JXXXX99APxxxxxx8Wxxxx1B results: - distinct_id: _distinct_id_ properties: name: Marge Simpson created_at: '2025-04-04T21:37:36.712496+00:00' updated_at: '2025-04-04T21:37:36.743167+00:00' schema: type: object properties: meta: type: object description: Metadata related to pagination. properties: count: type: integer description: Total number of records available. example: 1201709 limit: type: integer description: Maximum number of records per page. example: 10 has_prev: type: boolean description: Indicates if there is a previous page. example: false before: type: string nullable: true description: Cursor for the previous page. example: null has_next: type: boolean description: Indicates if there is a next page. example: true after: type: string description: Cursor for the next page. example: 01JXXXX99APxxxxxx8Wxxxx1B results: type: array description: List of users objects items: type: object properties: distinct_id: type: string description: Unique identifier of the user. example: _distinct_id_ properties: type: object description: User properties (simplified) created_at: type: string format: date-time description: Timestamp when the user was created. example: '2025-04-04T21:37:36.712496+00:00' updated_at: type: string format: date-time description: Timestamp when the user was last updated. example: '2025-04-04T21:37:36.743167+00:00' deprecated: false tags: - User /v1/user/{distinct_id}/merge/: post: summary: Merge User Profiles security: - BearerAuth: [] description: API to merge two user profiles to resolve duplicate user records. operationId: merge-users parameters: - name: distinct_id in: path description: Unique identifier of primary user schema: type: string required: true requestBody: content: application/json: schema: type: object properties: from_user_id: type: string description: Unique identifier of secondary user whose profile needs to be merged into primary user. responses: '201': description: 201 - Created content: application/json: examples: Result: value: distinct_id: _distinct_id_ properties: {} created_at: '2025-04-04T21:37:36.712496+00:00' updated_at: '2025-04-04T21:37:36.743167+00:00' $inbox: - value: 4nlPk4t4kurG5kChOELB8Q1LcDI9DHzHQ70st2E2C24 id_provider: suprsend status: active perma_status: active schema: type: object description: user object of the primary user after the merge. '404': description: 404 - Not Found content: application/json: examples: Result: value: code: 404 message: 'from_user_id: [distinct_id: ''secondary_user''] not found / user [distinct_id: ''primary_user''] not found' schema: type: object properties: code: type: integer description: HTTP status code indicating the error. example: 404 message: type: string description: Description of the error. example: 'user [distinct_id: ''user1''] not found' deprecated: false tags: - User /v1/user/{distinct_id}/subscribed_to/object/: get: summary: Fetch User object subscriptions security: - BearerAuth: [] description: API to fetch all objects that a given user is subscribed to. operationId: fetch-user-object-subscriptions parameters: - name: distinct_id in: path description: Unique identifier of the user in your system schema: type: string required: true - name: limit in: query description: number of results to be returned in API response required: false schema: type: integer format: int32 responses: '200': description: '200' content: application/json: examples: Result: value: meta: count: 4 limit: 1 has_prev: false before: null has_next: false after: null results: - properties: role: manager object: id: frontend object_type: department properties: {} subscriptions_count: 10 updated_at: '2025-01-28T16:49:23.695448+00:00' created_at: '2025-01-23T16:34:56.093683+00:00' updated_at: '2025-01-23T16:34:56.093683+00:00' schema: type: object properties: meta: type: object description: Metadata related to pagination. properties: count: type: integer description: Total number of results. example: 4 limit: type: integer description: The maximum number of results per request. example: 10 has_prev: type: boolean description: Indicates if there are previous results. example: false before: type: string nullable: true description: Cursor for fetching previous results. example: 01JXXXX99APxxxxxx8Wxxxx1B has_next: type: boolean description: Indicates if there are more results available. example: false after: type: string nullable: true description: Cursor for fetching next results. example: 02KXXXX99APxxxxxx0Wxxxx1A results: type: array description: List of retrieved results. items: type: object properties: properties: type: object description: Object subscription property referred as `$recipient.subscription.` in templates or workflows. object: type: object description: Details of the subscribed object. properties: id: type: string description: Unique identifier for the object. example: frontend object_type: type: string description: Type of object. example: department properties: type: object description: Additional properties related to the object. subscriptions_count: type: integer description: Number of active subscriptions associated with the object. example: 1 updated_at: type: string format: date-time description: Timestamp when the object was last updated. example: '2025-01-28T16:49:23.695448+00:00' created_at: type: string format: date-time description: Timestamp when the result was created. example: '2025-01-23T16:34:56.093683+00:00' updated_at: type: string format: date-time description: Timestamp when the result was last updated. example: '2025-01-23T16:34:56.093683+00:00' '404': description: 404 - Not Found content: application/json: examples: Result: value: code: 404 message: 'User [distinct_id: ''user1''] not found' schema: type: object properties: code: type: integer description: HTTP status code indicating the error type. example: 404 message: type: string description: Error message providing details about the issue. example: 'User [distinct_id: ''user1''] not found' deprecated: false tags: - User /v1/user/{distinct_id}/subscribed_to/list/: get: summary: Fetch User list subscriptions security: - BearerAuth: [] description: API to retrieve all lists that a user is part of. operationId: fetch-user-list-subscriptions parameters: - name: distinct_id in: path description: Unique identifier of the user in your system schema: type: string required: true - name: limit in: query description: number of results to be returned in API response required: false schema: type: integer format: int32 responses: '200': description: 200 - OK content: application/json: examples: Result: value: meta: count: 8 limit: 10 has_prev: false before: null has_next: false after: 01HPMFF5V2CFCF5882QX9FQXYB results: - list: list_description: List of users to send newsletter to (Qualified leads + Product Users) list_id: product_update list_name: '' list_type: static_list source: csv_upload subscribers_count: 2 updated_at: '2024-09-26T10:20:33.636698+00:00' created_at: '2024-08-04T13:16:12.825+00:00' schema: type: object properties: meta: type: object description: Metadata related to pagination. properties: count: type: integer description: Total number of records returned. example: 8 limit: type: integer description: Maximum number of records per page. example: 10 has_prev: type: boolean description: Indicates if there is a previous page. example: false before: type: string nullable: true description: Cursor for the previous page. example: 01HPMFF5V2CFCF5882QX9FQXYB has_next: type: boolean description: Indicates if there is a next page. example: false after: type: string nullable: true description: Cursor for the next page. example: 01HPMFF5V2CFCFti5882QX9FQXYB results: type: array description: List of user lists. items: type: object properties: list: type: object properties: list_id: type: string description: Unique identifier for the list. example: product_update list_name: type: string description: Name of the list. example: Newsletter subscriber users description: type: string description: Brief description of the list. example: List of users to send newsletter to list_type: type: string description: Type of list (static_list, query_based) example: static_list source: type: string nullable: true description: Source from which the list was created (csv_upload, database_sync, mixpanel) example: csv_upload subscribers_count: type: integer description: Number of subscribers in the list. example: 2 updated_at: type: string format: date-time description: Timestamp when the list was last updated. example: '2024-09-26T10:20:33.636698+00:00' created_at: type: string format: date-time description: Timestamp when the user was added to the list. example: '2024-09-26T10:20:33.636698+00:00' '404': description: 404 - Not Found content: application/json: examples: Result: value: code: 404 message: 'user [distinct_id: ''user1''] not found' schema: type: object properties: code: type: integer description: HTTP error status code. example: 404 message: type: string description: Error message describing the issue. example: 'user [distinct_id: ''user1''] not found' deprecated: false tags: - User components: securitySchemes: 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. sec0: type: apiKey in: header name: Authorization x-bearer-format: bearer description: Bearer authentication header of the form `Bearer `, where is your auth token. x-readme: headers: [] explorer-enabled: true proxy-enabled: true x-readme-fauxas: true