Extole User Subscriptions API
The User Subscriptions API from Extole — 3 operation(s) for user subscriptions.
OpenAPI Specification
openapi: 3.0.1
info:
description: 'Consumer-to-Extole integration endpoints: consumer event submission, zone rendering, profile management, and SDK-backing operations for browser and native app environments.'
title: Integration API - Consumer to Extole Audiences User Subscriptions API
version: '1.0'
servers:
- description: Production
url: https://{brand}.extole.io
variables:
brand:
default: yourcompany
description: Your Extole client subdomain (e.g. 'mycompany' for mycompany.extole.io)
security:
- HEADER: []
- QUERY: []
- COOKIE: []
tags:
- name: User Subscriptions
paths:
/v6/subscriptions:
get:
description: Returns all notification subscriptions for the calling client, optionally filtered by tags. Use `having_any_tags` to match subscriptions that have at least one of the specified tags, or `having_all_tags` to match subscriptions that have all specified tags.
operationId: listSubscriptions
parameters:
- in: query
name: having_any_tags
schema:
nullable: true
type: string
- in: query
name: having_all_tags
schema:
nullable: true
type: string
responses:
'200':
content:
application/json:
schema:
items:
$ref: '#/components/schemas/SubscriptionResponse'
type: array
description: Successful response
'400':
content:
application/json:
examples:
binding_error:
$ref: '#/components/examples/binding_error'
invalid_json:
$ref: '#/components/examples/invalid_json'
invalid_parameter:
$ref: '#/components/examples/invalid_parameter'
missing_request_body:
$ref: '#/components/examples/missing_request_body'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Bad Request
'401':
content:
application/json:
examples:
method_unauthorized:
$ref: '#/components/examples/method_unauthorized'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Unauthorized
'402':
content:
application/json:
examples:
payment_required:
$ref: '#/components/examples/payment_required'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Payment Required
'403':
content:
application/json:
examples:
access_denied:
$ref: '#/components/examples/access_denied'
method_unauthorized:
$ref: '#/components/examples/method_unauthorized'
missing_access_token:
$ref: '#/components/examples/missing_access_token'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Forbidden
'415':
content:
application/json:
examples:
unsupported_media_type:
$ref: '#/components/examples/unsupported_media_type'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Unsupported Media Type
'429':
content:
application/json:
examples:
too_many_requests:
$ref: '#/components/examples/too_many_requests'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Too Many Requests
summary: List subscriptions
tags:
- User Subscriptions
x-extole-bundle: management
x-extole-visibility: visible
/v6/users/{user_id}/subscriptions:
get:
description: Returns all notification subscriptions for the specified Extole user. Subscriptions define which report or alert events the user wants to be notified about and through which channel (email, Slack, webhook).
operationId: listUserSubscriptions
parameters:
- description: The unique identifier of this user at Extole.
in: path
name: user_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
items:
$ref: '#/components/schemas/UserSubscriptionResponse'
type: array
description: Successful response
'400':
content:
application/json:
examples:
binding_error:
$ref: '#/components/examples/binding_error'
invalid_json:
$ref: '#/components/examples/invalid_json'
invalid_parameter:
$ref: '#/components/examples/invalid_parameter'
invalid_user_id:
$ref: '#/components/examples/invalid_user_id'
missing_request_body:
$ref: '#/components/examples/missing_request_body'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Bad Request
'401':
content:
application/json:
examples:
method_unauthorized:
$ref: '#/components/examples/method_unauthorized'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Unauthorized
'402':
content:
application/json:
examples:
payment_required:
$ref: '#/components/examples/payment_required'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Payment Required
'403':
content:
application/json:
examples:
access_denied:
$ref: '#/components/examples/access_denied'
invalid_scope:
$ref: '#/components/examples/invalid_scope'
method_unauthorized:
$ref: '#/components/examples/method_unauthorized'
missing_access_token:
$ref: '#/components/examples/missing_access_token'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Forbidden
'415':
content:
application/json:
examples:
unsupported_media_type:
$ref: '#/components/examples/unsupported_media_type'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Unsupported Media Type
'429':
content:
application/json:
examples:
too_many_requests:
$ref: '#/components/examples/too_many_requests'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Too Many Requests
summary: List user subscriptions
tags:
- User Subscriptions
x-extole-bundle: management
x-extole-visibility: visible
post:
description: Creates a new notification subscription for the specified user. The request body specifies the event type to subscribe to and the delivery channel (email, Slack, or webhook). Returns the created subscription.
operationId: createUserSubscription
parameters:
- description: The unique identifier of this user at Extole.
in: path
name: user_id
required: true
schema:
type: string
requestBody:
content:
application/json:
example:
channels:
- type: EMAIL
dedupe_duration_ms: 1
filter_expression: true
filtering_level: ALL
having_all_tags:
- having_all_tag
schema:
$ref: '#/components/schemas/UserSubscriptionRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/UserSubscriptionResponse'
description: Successful response
'400':
content:
application/json:
examples:
binding_error:
$ref: '#/components/examples/binding_error'
handlebars_expression_invalid_syntax:
$ref: '#/components/examples/handlebars_expression_invalid_syntax'
invalid_channel_types_for_zero_dedupe_duration:
$ref: '#/components/examples/invalid_channel_types_for_zero_dedupe_duration'
invalid_dedupe_duration:
$ref: '#/components/examples/invalid_dedupe_duration'
invalid_json:
$ref: '#/components/examples/invalid_json'
invalid_parameter:
$ref: '#/components/examples/invalid_parameter'
invalid_recipient:
$ref: '#/components/examples/invalid_recipient'
invalid_tags:
$ref: '#/components/examples/invalid_tags'
invalid_user_id:
$ref: '#/components/examples/invalid_user_id'
invalid_webhook_type:
$ref: '#/components/examples/invalid_webhook_type'
javascript_expression_invalid_syntax:
$ref: '#/components/examples/javascript_expression_invalid_syntax'
missing_recipient:
$ref: '#/components/examples/missing_recipient'
missing_request_body:
$ref: '#/components/examples/missing_request_body'
recipient_is_existing_user:
$ref: '#/components/examples/recipient_is_existing_user'
spel_expression_invalid_syntax:
$ref: '#/components/examples/spel_expression_invalid_syntax'
user_subscription_channel_malformed_webhook_url:
$ref: '#/components/examples/user_subscription_channel_malformed_webhook_url'
user_subscription_channel_missing_slack_webhook_url:
$ref: '#/components/examples/user_subscription_channel_missing_slack_webhook_url'
webhook_not_found:
$ref: '#/components/examples/webhook_not_found'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Bad Request
'401':
content:
application/json:
examples:
method_unauthorized:
$ref: '#/components/examples/method_unauthorized'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Unauthorized
'402':
content:
application/json:
examples:
payment_required:
$ref: '#/components/examples/payment_required'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Payment Required
'403':
content:
application/json:
examples:
access_denied:
$ref: '#/components/examples/access_denied'
duplicate_user_subscription:
$ref: '#/components/examples/duplicate_user_subscription'
invalid_scope:
$ref: '#/components/examples/invalid_scope'
method_unauthorized:
$ref: '#/components/examples/method_unauthorized'
missing_access_token:
$ref: '#/components/examples/missing_access_token'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Forbidden
'415':
content:
application/json:
examples:
unsupported_media_type:
$ref: '#/components/examples/unsupported_media_type'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Unsupported Media Type
'429':
content:
application/json:
examples:
too_many_requests:
$ref: '#/components/examples/too_many_requests'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Too Many Requests
summary: Create a user subscription
tags:
- User Subscriptions
x-extole-bundle: management
x-extole-visibility: visible
/v6/users/{user_id}/subscriptions/{subscription_id}:
get:
description: Returns the specified notification subscription for the given user. Returns `400 invalid_subscription_id` if the subscription does not exist.
operationId: getUserSubscription
parameters:
- description: The unique identifier of this user at Extole.
in: path
name: user_id
required: true
schema:
type: string
- in: path
name: subscription_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/UserSubscriptionResponse'
description: User subscription.
'400':
content:
application/json:
examples:
invalid_subscription_id:
$ref: '#/components/examples/invalid_subscription_id'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Subscription was not found. The supplied id does not match any subscription for the given user.
'401':
content:
application/json:
examples:
method_unauthorized:
$ref: '#/components/examples/method_unauthorized'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Unauthorized
'402':
content:
application/json:
examples:
payment_required:
$ref: '#/components/examples/payment_required'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Payment Required
'403':
content:
application/json:
examples:
access_denied:
$ref: '#/components/examples/access_denied'
invalid_scope:
$ref: '#/components/examples/invalid_scope'
method_unauthorized:
$ref: '#/components/examples/method_unauthorized'
missing_access_token:
$ref: '#/components/examples/missing_access_token'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Forbidden
'415':
content:
application/json:
examples:
unsupported_media_type:
$ref: '#/components/examples/unsupported_media_type'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Unsupported Media Type
'429':
content:
application/json:
examples:
too_many_requests:
$ref: '#/components/examples/too_many_requests'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Too Many Requests
summary: Get a user subscription
tags:
- User Subscriptions
x-extole-bundle: management
x-extole-visibility: visible
put:
description: Updates the specified notification subscription for the given user. Returns `400 invalid_subscription_id` if the subscription does not exist.
operationId: updateUserSubscription
parameters:
- description: The unique identifier of this user at Extole.
in: path
name: user_id
required: true
schema:
type: string
- in: path
name: subscription_id
required: true
schema:
type: string
requestBody:
content:
application/json:
example:
channels:
- type: EMAIL
dedupe_duration_ms: 1
filter_expression: true
filtering_level: ALL
having_all_tags:
- having_all_tag
schema:
$ref: '#/components/schemas/UserSubscriptionUpdateRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/UserSubscriptionResponse'
description: Updated user subscription.
'400':
content:
application/json:
examples:
invalid_subscription_id:
$ref: '#/components/examples/invalid_subscription_id'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Subscription was not found. The supplied id does not match any subscription for the given user.
'401':
content:
application/json:
examples:
method_unauthorized:
$ref: '#/components/examples/method_unauthorized'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Unauthorized
'402':
content:
application/json:
examples:
payment_required:
$ref: '#/components/examples/payment_required'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Payment Required
'403':
content:
application/json:
examples:
access_denied:
$ref: '#/components/examples/access_denied'
duplicate_user_subscription:
$ref: '#/components/examples/duplicate_user_subscription'
invalid_scope:
$ref: '#/components/examples/invalid_scope'
method_unauthorized:
$ref: '#/components/examples/method_unauthorized'
missing_access_token:
$ref: '#/components/examples/missing_access_token'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Forbidden
'415':
content:
application/json:
examples:
unsupported_media_type:
$ref: '#/components/examples/unsupported_media_type'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Unsupported Media Type
'429':
content:
application/json:
examples:
too_many_requests:
$ref: '#/components/examples/too_many_requests'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Too Many Requests
summary: Update a user subscription
tags:
- User Subscriptions
x-extole-bundle: management
x-extole-visibility: visible
delete:
description: Permanently deletes the specified notification subscription. The user will no longer receive notifications for the subscribed event type via that channel. Returns `400 invalid_subscription_id` if the subscription does not exist.
operationId: deleteUserSubscription
parameters:
- description: The unique identifier of this user at Extole.
in: path
name: user_id
required: true
schema:
type: string
- in: path
name: subscription_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
description: User subscription deleted.
'400':
content:
application/json:
examples:
invalid_subscription_id:
$ref: '#/components/examples/invalid_subscription_id'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Subscription was not found. The supplied id does not match any subscription for the given user.
'401':
content:
application/json:
examples:
method_unauthorized:
$ref: '#/components/examples/method_unauthorized'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Unauthorized
'402':
content:
application/json:
examples:
payment_required:
$ref: '#/components/examples/payment_required'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Payment Required
'403':
content:
application/json:
examples:
access_denied:
$ref: '#/components/examples/access_denied'
invalid_scope:
$ref: '#/components/examples/invalid_scope'
method_unauthorized:
$ref: '#/components/examples/method_unauthorized'
missing_access_token:
$ref: '#/components/examples/missing_access_token'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Forbidden
'415':
content:
application/json:
examples:
unsupported_media_type:
$ref: '#/components/examples/unsupported_media_type'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Unsupported Media Type
'429':
content:
application/json:
examples:
too_many_requests:
$ref: '#/components/examples/too_many_requests'
schema:
$ref: '#/components/schemas/RestExceptionResponse'
description: Too Many Requests
summary: Delete a user subscription
tags:
- User Subscriptions
x-extole-bundle: management
x-extole-visibility: visible
components:
examples:
invalid_json:
summary: invalid_json
value:
code: invalid_json
http_status_code: 400
message: JSON is invalid
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
user_subscription_channel_missing_slack_webhook_url:
summary: user_subscription_channel_missing_slack_webhook_url
value:
code: user_subscription_channel_missing_slack_webhook_url
http_status_code: 400
message: WebhookUrl is missing
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
user_subscription_channel_malformed_webhook_url:
summary: user_subscription_channel_malformed_webhook_url
value:
code: user_subscription_channel_malformed_webhook_url
http_status_code: 400
message: Malformed webhook url
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
duplicate_user_subscription:
summary: duplicate_user_subscription
value:
code: duplicate_user_subscription
http_status_code: 403
message: User subscription already exists
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
invalid_scope:
summary: invalid_scope
value:
code: invalid_scope
http_status_code: 403
message: Invalid scope
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
invalid_recipient:
summary: invalid_recipient
value:
code: invalid_recipient
http_status_code: 400
message: Recipient email is invalid
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
missing_access_token:
summary: missing_access_token
value:
code: missing_access_token
http_status_code: 403
message: No access_token was provided with this request.
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
payment_required:
summary: payment_required
value:
code: payment_required
http_status_code: 402
message: The access_token provided is associated with an unpaid account.
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
invalid_dedupe_duration:
summary: invalid_dedupe_duration
value:
code: invalid_dedupe_duration
http_status_code: 400
message: unacceptable dedupe duration
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
unsupported_media_type:
summary: unsupported_media_type
value:
code: unsupported_media_type
http_status_code: 415
message: Request had an unsupported or no media type
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
method_unauthorized:
summary: method_unauthorized
value:
code: method_unauthorized
http_status_code: 401
message: Unauthorized access to this endpoint
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
invalid_webhook_type:
summary: invalid_webhook_type
value:
code: invalid_webhook_type
http_status_code: 400
message: Webhook type is invalid
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
missing_recipient:
summary: missing_recipient
value:
code: missing_recipient
http_status_code: 400
message: Recipient email is missing
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
invalid_subscription_id:
summary: invalid_subscription_id
value:
code: invalid_subscription_id
http_status_code: 400
message: Invalid subscription id
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
recipient_is_existing_user:
summary: recipient_is_existing_user
value:
code: recipient_is_existing_user
http_status_code: 400
message: Recipient email belongs to an existing user
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
missing_request_body:
summary: missing_request_body
value:
code: missing_request_body
http_status_code: 400
message: Missing request body
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
binding_error:
summary: binding_error
value:
code: binding_error
http_status_code: 400
message: Argument is not of the expected type
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
access_denied:
summary: access_denied
value:
code: access_denied
http_status_code: 403
message: The access_token provided is not permitted to access the specified resource.
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
handlebars_expression_invalid_syntax:
summary: handlebars_expression_invalid_syntax
value:
code: handlebars_expression_invalid_syntax
http_status_code: 400
message: Expression has invalid syntax and/or contains forbidden statements
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
too_many_requests:
summary: too_many_requests
value:
code: too_many_requests
http_status_code: 429
message: The server is unable to process your request at the moment, please retry later.
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
invalid_user_id:
summary: invalid_user_id
value:
code: invalid_user_id
http_status_code: 400
message: Invalid user id
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
invalid_channel_types_for_zero_dedupe_duration:
summary: invalid_channel_types_for_zero_dedupe_duration
value:
code: invalid_channel_types_for_zero_dedupe_duration
http_status_code: 400
message: invalid channel types for 0ms dedupe duration
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
invalid_parameter:
summary: invalid_parameter
value:
code: invalid_parameter
http_status_code: 400
message: Parameter is invalid.
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
javascript_expression_invalid_syntax:
summary: javascript_expression_invalid_syntax
value:
code: javascript_expression_invalid_syntax
http_status_code: 400
message: Expression has invalid syntax and/or contains forbidden statements
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
invalid_tags:
summary: invalid_tags
value:
code: invalid_tags
http_status_code: 400
message: total length of tags cannot exceed 1024 characters
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
webhook_not_found:
summary: webhook_not_found
value:
code: webhook_not_found
http_status_code: 400
message: Was unable to find webhook with id
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
spel_expression_invalid_syntax:
summary: spel_expression_invalid_syntax
value:
code: spel_expression_invalid_syntax
http_status_code: 400
message: Expression has invalid syntax and/or contains forbidden statements
parameters: {}
unique_id: 00000000-0000-0000-0000-000000000000
schemas:
WebhookSubscriptionChannelRequest:
allOf:
- $ref: '#/components/schemas/SubscriptionChannelRequestBase'
- properties:
type:
enum:
- WEBHOOK
type: string
webhook_id:
type: string
type: object
required:
- type
- webhook_id
type: object
SubscriptionUserResponse:
properties:
email:
type: string
first_name:
nullable: true
type: string
last_name:
nullable: true
type: string
user_id:
type: string
type: object
FilterExpressionInUserSubscriptionRequest:
description: Choose between static or dynamic filter expression
oneOf:
- description: Static filter expression
title: Static Value
type: boolean
- description: Handlebars expression with [UserSubscriptionFilterContext](https://github.com/extole/extole-specification/blob/main/openapi/expression-context/com/extole/api/notification/subscription/UserSubscriptionFilterContext.d.ts).
example: handlebars@runtime:{{filterExpression}}
externalDocs:
description: UserSubscriptionFilterContext
url: https://github.com/extole/extole-specification/blob/main/openapi/expression-context/com/extole/api/notification/subscription/UserSubscriptionFilterContext.d.ts
pattern: ^handlebars@runtime:.*
title: Runtime - Handlebars
type: string
- description: Javascript expression with [UserSubscriptionFilterContext](https://github.com/extole/extole-specification/blob/main/openapi/expression-context/com/extole/api/notification/subscription/UserSubscriptionFilterContext.d.ts).
exampl
# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/extole/refs/heads/main/openapi/extole-user-subscriptions-api-openapi.yml