> ## Documentation Index
> Fetch the complete documentation index at: https://doc.extole.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a user subscription

> 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.



## OpenAPI

````yaml /api-reference/management.json post /v6/users/{user_id}/subscriptions
openapi: 3.0.1
info:
  description: >-
    Configuration endpoints for the Extole platform: campaigns, components,
    audiences, persons, rewards, reporting, integrations setup, and
    administrative tooling.
  title: Management API
  version: '1.0'
servers:
  - description: Production
    url: https://api.extole.io
security:
  - HEADER: []
  - QUERY: []
  - COOKIE: []
tags:
  - name: Audiences
  - name: Authentication
  - name: Batch Jobs
  - name: Blocks
  - name: Campaigns
  - name: Components
  - name: Components Settings
  - name: Domains
  - name: Email
  - name: Erasure
  - name: Event Streams
  - name: File Validation Monitors
  - name: Optout
  - name: Profiles
  - name: Promotion Links
  - name: Report Schedules
  - name: Report Types
  - name: Reports
  - name: Reward Suppliers
  - name: Security Keys
  - name: Settings
  - name: User Notifications
  - name: User Subscriptions
  - name: Users
  - name: Webhooks
paths:
  /v6/users/{user_id}/subscriptions:
    post:
      tags:
        - User Subscriptions
      summary: Create a user subscription
      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
components:
  schemas:
    UserSubscriptionRequest:
      properties:
        channels:
          items:
            $ref: '#/components/schemas/SubscriptionChannelRequest'
          type: array
        dedupe_duration_ms:
          format: int64
          type: integer
        filter_expression:
          $ref: '#/components/schemas/FilterExpressionInUserSubscriptionRequest'
        filtering_level:
          enum:
            - ALL
            - NONE
            - NOTEWORTHY
            - SOME
          type: string
        having_all_tags:
          items:
            type: string
          type: array
          uniqueItems: true
      required:
        - filtering_level
        - having_all_tags
      type: object
    UserSubscriptionResponse:
      properties:
        channels:
          items:
            $ref: '#/components/schemas/SubscriptionChannelResponse'
          type: array
        dedupe_duration_ms:
          format: int64
          type: integer
        filter_expression:
          $ref: '#/components/schemas/FilterExpressionInUserSubscriptionResponse'
        filtering_level:
          enum:
            - ALL
            - NONE
            - NOTEWORTHY
            - SOME
          type: string
        having_all_tags:
          items:
            type: string
          type: array
          uniqueItems: true
        subscription_id:
          type: string
      required:
        - channels
        - dedupe_duration_ms
        - filter_expression
        - filtering_level
        - having_all_tags
        - subscription_id
      type: object
    RestExceptionResponse:
      description: Represents the API error response
      properties:
        code:
          description: Specific error code for this error type, documented per endpoint
          type: string
        http_status_code:
          description: >-
            HTTP status code that was returned with this error, useful if client
            get response code
          format: int32
          type: integer
        message:
          description: User readable English description of the error
          type: string
        parameters:
          additionalProperties:
            description: >-
              Attributes related to the error, varies be error code, documented
              per endpoint
            type: object
          description: >-
            Attributes related to the error, varies be error code, documented
            per endpoint
          type: object
        unique_id:
          description: >-
            Unique id associated with this error, useful for discussions with
            Extole
          type: string
      required:
        - code
        - http_status_code
        - message
        - parameters
        - unique_id
      type: object
    SubscriptionChannelRequest:
      discriminator:
        mapping:
          EMAIL:
            $ref: '#/components/schemas/EmailSubscriptionChannelRequest'
          EXTOLE_CLIENT_SLACK:
            $ref: '#/components/schemas/ExtoleClientSlackSubscriptionChannelRequest'
          SLACK:
            $ref: '#/components/schemas/SlackSubscriptionChannelRequest'
          THIRD_PARTY_EMAIL:
            $ref: '#/components/schemas/ThirdPartyEmailSubscriptionChannelRequest'
          WEBHOOK:
            $ref: '#/components/schemas/WebhookSubscriptionChannelRequest'
        propertyName: type
      oneOf:
        - title: EMAIL
          allOf:
            - $ref: '#/components/schemas/EmailSubscriptionChannelRequest'
        - title: EXTOLE_CLIENT_SLACK
          allOf:
            - $ref: '#/components/schemas/ExtoleClientSlackSubscriptionChannelRequest'
        - title: SLACK
          allOf:
            - $ref: '#/components/schemas/SlackSubscriptionChannelRequest'
        - title: THIRD_PARTY_EMAIL
          allOf:
            - $ref: '#/components/schemas/ThirdPartyEmailSubscriptionChannelRequest'
        - title: WEBHOOK
          allOf:
            - $ref: '#/components/schemas/WebhookSubscriptionChannelRequest'
    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).
          example: >-
            javascript@runtime:function() { return
            context.get('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: ^javascript@runtime:.*
          title: Runtime - Javascript
          type: string
    SubscriptionChannelResponse:
      discriminator:
        mapping:
          EMAIL:
            $ref: '#/components/schemas/EmailSubscriptionChannelResponse'
          EXTOLE_CLIENT_SLACK:
            $ref: '#/components/schemas/ExtoleClientSlackSubscriptionChannelResponse'
          SLACK:
            $ref: '#/components/schemas/SlackSubscriptionChannelResponse'
          THIRD_PARTY_EMAIL:
            $ref: '#/components/schemas/ThirdPartyEmailSubscriptionChannelResponse'
          WEBHOOK:
            $ref: '#/components/schemas/WebhookSubscriptionChannelResponse'
        propertyName: type
      oneOf:
        - title: EMAIL
          allOf:
            - $ref: '#/components/schemas/EmailSubscriptionChannelResponse'
        - title: EXTOLE_CLIENT_SLACK
          allOf:
            - $ref: >-
                #/components/schemas/ExtoleClientSlackSubscriptionChannelResponse
        - title: SLACK
          allOf:
            - $ref: '#/components/schemas/SlackSubscriptionChannelResponse'
        - title: THIRD_PARTY_EMAIL
          allOf:
            - $ref: '#/components/schemas/ThirdPartyEmailSubscriptionChannelResponse'
        - title: WEBHOOK
          allOf:
            - $ref: '#/components/schemas/WebhookSubscriptionChannelResponse'
    FilterExpressionInUserSubscriptionResponse:
      description: >-
        The filter expression as configured: a literal value, or an expression
        (type:string) when defined dynamically.
      oneOf:
        - description: Literal 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).
          example: >-
            javascript@runtime:function() { return
            context.get('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: ^javascript@runtime:.*
          title: Runtime - Javascript
          type: string
    EmailSubscriptionChannelRequest:
      allOf:
        - $ref: '#/components/schemas/SubscriptionChannelRequestBase'
        - properties:
            type:
              enum:
                - EMAIL
              type: string
      required:
        - type
      type: object
      title: EMAIL
    ExtoleClientSlackSubscriptionChannelRequest:
      allOf:
        - $ref: '#/components/schemas/SubscriptionChannelRequestBase'
        - properties:
            type:
              enum:
                - EXTOLE_CLIENT_SLACK
              type: string
      required:
        - type
      type: object
      title: EXTOLE_CLIENT_SLACK
    SlackSubscriptionChannelRequest:
      allOf:
        - $ref: '#/components/schemas/SubscriptionChannelRequestBase'
        - properties:
            type:
              enum:
                - SLACK
              type: string
            webhook_url:
              type: string
          type: object
      required:
        - type
        - webhook_url
      type: object
      title: SLACK
    ThirdPartyEmailSubscriptionChannelRequest:
      allOf:
        - $ref: '#/components/schemas/SubscriptionChannelRequestBase'
        - properties:
            recipient:
              type: string
            type:
              enum:
                - THIRD_PARTY_EMAIL
              type: string
          type: object
      required:
        - recipient
        - type
      type: object
      title: THIRD_PARTY_EMAIL
    WebhookSubscriptionChannelRequest:
      allOf:
        - $ref: '#/components/schemas/SubscriptionChannelRequestBase'
        - properties:
            type:
              enum:
                - WEBHOOK
              type: string
            webhook_id:
              type: string
          type: object
      required:
        - type
        - webhook_id
      type: object
      title: WEBHOOK
    EmailSubscriptionChannelResponse:
      allOf:
        - $ref: '#/components/schemas/SubscriptionChannelResponseBase'
        - properties:
            id:
              readOnly: true
              type: string
            type:
              enum:
                - EMAIL
              type: string
          type: object
      required:
        - id
        - type
      type: object
      title: EMAIL
    ExtoleClientSlackSubscriptionChannelResponse:
      allOf:
        - $ref: '#/components/schemas/SubscriptionChannelResponseBase'
        - properties:
            id:
              readOnly: true
              type: string
            type:
              enum:
                - EXTOLE_CLIENT_SLACK
              type: string
          type: object
      required:
        - id
        - type
      type: object
      title: EXTOLE_CLIENT_SLACK
    SlackSubscriptionChannelResponse:
      allOf:
        - $ref: '#/components/schemas/SubscriptionChannelResponseBase'
        - properties:
            id:
              readOnly: true
              type: string
            type:
              enum:
                - SLACK
              type: string
            webhook_url:
              type: string
          type: object
      required:
        - id
        - type
        - webhook_url
      type: object
      title: SLACK
    ThirdPartyEmailSubscriptionChannelResponse:
      allOf:
        - $ref: '#/components/schemas/SubscriptionChannelResponseBase'
        - properties:
            id:
              readOnly: true
              type: string
            recipient:
              type: string
            type:
              enum:
                - THIRD_PARTY_EMAIL
              type: string
          type: object
      required:
        - id
        - recipient
        - type
      type: object
      title: THIRD_PARTY_EMAIL
    WebhookSubscriptionChannelResponse:
      allOf:
        - $ref: '#/components/schemas/SubscriptionChannelResponseBase'
        - properties:
            id:
              readOnly: true
              type: string
            type:
              enum:
                - WEBHOOK
              type: string
            webhook_id:
              type: string
          type: object
      required:
        - id
        - type
        - webhook_id
      type: object
      title: WEBHOOK
    SubscriptionChannelRequestBase:
      properties:
        type:
          enum:
            - EMAIL
            - EXTOLE_CLIENT_SLACK
            - SLACK
            - THIRD_PARTY_EMAIL
            - WEBHOOK
          type: string
      type: object
    SubscriptionChannelResponseBase:
      properties:
        id:
          type: string
        type:
          enum:
            - EMAIL
            - EXTOLE_CLIENT_SLACK
            - SLACK
            - THIRD_PARTY_EMAIL
            - WEBHOOK
          type: string
      type: object
  examples:
    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
    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
    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_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
    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
    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
    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
    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
    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_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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
  securitySchemes:
    HEADER:
      in: header
      name: Authorization
      type: apiKey
      x-bearer-format: bearer
    QUERY:
      in: query
      name: access_token
      type: apiKey
    COOKIE:
      in: cookie
      name: extole_token
      type: apiKey

````