openapi: 3.2.0
info:
  title: Exclaimer Cloud Subscription Users API
  version: '1'
  description: The Subscription Users operations of the Exclaimer Cloud API, the partner/distributor provisioning API for Exclaimer Cloud tenants. Split by tag from the provider-published OpenAPI at https://cloudapi.exclaimer.com/openapi.json (documentation version 5.2, published 2025-07-23). Operation content is carried verbatim from the source specification.
servers:
- url: https://cloudapi.exclaimer.com/exclaimerapi
  description: Local
security:
- Exclaimer: []
tags:
- name: Subscription Users
paths:
  /1.0/subscriptions/{SubscriptionID}/users:
    post:
      tags:
      - Subscription Users
      summary: Add Subscription User
      description: This request allows you to add new users to a subscription. <p> The same user can be added to multiple subscriptions. </p><p> Note that you cannot modify an existing subscription user with this API. However, if the user has previously been deleted, they can be re-added. </p>
      parameters:
      - name: SubscriptionID
        in: path
        description: Your reference for the subscription. This is the same ID you specified, or was automatically generated, when the subscription was created, i.e. when calling <b>Add Subscription</b>.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddSubscriptionUser'
            examples:
              Basic usage:
                value: '{"UserID":"S-JF-093","EmailAddress":"sales.john.fisher@example.com","Roles":["Admin","Editor"]}'
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request / Missing Field
        '401':
          description: Unauthorized
        '415':
          description: Unsupported Media Type
        '500':
          description: Internal Server Error
      x-documentation:
        curlExamples:
          Basic usage - cURL:
            description: /subscriptions/EX-Subscription-001/users
            value: '{"UserID":"EX-User-003","EmailAddress":"ex.user.003@example.com","Roles":["Admin","Editor"],"SendWelcomeEmailToCustomer":false}'
    get:
      tags:
      - Subscription Users
      summary: Get Subscription Users
      description: This request will return details of each of the users for a given subscription. If there are currently no users against the subscription, an empty array will be returned.
      parameters:
      - name: SubscriptionID
        in: path
        description: Your reference for the subscription. This is the same ID you specified, or was automatically generated, when the subscription was created, i.e., when calling <b>Add Subscription</b>.
        required: true
        schema:
          type: string
      - name: Page
        in: query
        description: Page numbers start at 1. <p> See the section <b>"Paging of results"</b> at the beginning of the document.<br /> Results are ordered by the date the subscription was added. </p>
        schema:
          type: number
          format: int32
      - name: PageSize
        in: query
        description: Defaults to 50. Maximum 200. <p> See the section <b>"Paging of results"</b> at the beginning of the document.<br /></p>
        schema:
          type: number
          format: int32
      - name: ContinuationToken
        in: query
        description: A token that can be used to get the next page of results without supplying paging values.
        schema:
          type: number
          format: int32
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionUsersResponse'
              examples:
                Basic response:
                  value: '{"Users":[{"Email":"finance.harry.miles@example.com","UserID":"FIN-HM-102","Roles":["Admin"]},{"Email":"finance.robert.davis@example.com","UserID":"FIN-RD-005","Roles":["Admin","Editor"]}],"UserCount":21,"ContinuationToken":262145,"Page":6,"PageSize":2}'
        '400':
          description: Bad Request / Missing Field
        '401':
          description: Unauthorized
        '404':
          description: Not Found
        '500':
          description: Internal Server Error
      x-documentation:
        routeExamples:
          Basic usage:
            value: /subscriptions/SUB-SXU-409/users
          Paging:
            value: /subscriptions/SUB-FFP-381/users?Page=6&PageSize=2
          Using a continuation token:
            value: /subscriptions/SUB-LMQ-598/users?ContinuationToken=262145
        curlExamples:
          Basic usage - cURL:
            description: /subscriptions/EX-Subscription-001/users
            value: '{}'
  /1.0/subscriptions/{SubscriptionID}/users/{UserID}:
    delete:
      tags:
      - Subscription Users
      summary: Delete Subscription User
      description: This request allows you to remove a user from a subscription. <p> Note that this only removes the user from the specified subscription. If they have also been added to other subscriptions, those will remain unaffected. </p><p> You cannot remove the subscription owner, added during <b>Add Subscription</b>. You will receive a 403 Forbidden if you try. </p><p> If you wish to re-add a deleted user, just call <b>Add Subscription User</b> again. </p>
      parameters:
      - name: SubscriptionID
        in: path
        description: Your reference for the subscription. This is the same ID you specified, or was automatically generated, when the subscription was created, i.e., when calling <b>Add Subscription</b>.
        required: true
        schema:
          type: string
      - name: UserID
        in: path
        description: This can either be your reference for the user, or the user's email address.<br /> Both of these are the same as the ID you specified, or was automatically generated, or the email address used, when the subscription was created i.e., when calling <b>Add Subscription</b>, or when adding a user through <b>Add Subscription User</b>.
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request / Missing Field
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '415':
          description: Unsupported Media Type
        '500':
          description: Internal Server Error
      x-documentation:
        routeExamples:
          Basic usage:
            value: /subscriptions/SUB-VBY-329/users/HazelWild
          Delete using an email address:
            value: /subscriptions/SUB-JWO-830/users/george.miller@example.com
        curlExamples:
          Basic usage - cURL:
            description: /subscriptions/EX-Subscription-001/users/EX-User-003
            value: '{}'
          Delete using an email address - cURL:
            description: /subscriptions/EX-Subscription-002/users/george.miller@example.com
            value: '{}'
  /1.0/subscriptions/users:
    get:
      tags:
      - Subscription Users
      summary: Get All Subscription Users
      description: This request returns a list of all users across all of your subscriptions. <p> An entry is returned for each unique user along with details of which subscriptions they have access to, and the roles they're assigned within those subscriptions. </p><p> The same user, determined by email address, can have a different UserID within each subscription. </p>
      parameters:
      - name: Page
        in: query
        description: Page numbers start at 1. <p> See the section <b>"Paging of results"</b> at the beginning of the document.<br /> Results are ordered by the date the subscription was added. </p>
        schema:
          type: number
          format: int32
      - name: PageSize
        in: query
        description: Defaults to 50. Maximum 200. <p> See the section <b>"Paging of results"</b> at the beginning of the document.<br /></p>
        schema:
          type: number
          format: int32
      - name: ContinuationToken
        in: query
        description: A token that can be used to get the next page of results without supplying paging values.
        schema:
          type: number
          format: int32
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DistributorLevelSubscriptionUsersResponse'
              examples:
                Basic response:
                  value: '{"Users":[{"Email":"brian.anderson@example.com","Subscriptions":[{"SubscriptionID":"SA-189036-S001","UserID":"SA-189036-U001","Roles":["Admin","Editor"]}]},{"Email":"joan.jones@example.com","Subscriptions":[{"SubscriptionID":"SA-189036-S001","UserID":"SA-189036-U002","Roles":["Admin","Editor"]},{"SubscriptionID":"TK-549109-S001","UserID":"TK-549109-U001","Roles":["Admin"]},{"SubscriptionID":"TK-549109-S002","UserID":"TK-549109-U002","Roles":["Editor"]}]}],"UserCount":21,"ContinuationToken":262145,"Page":6,"PageSize":2}'
        '400':
          description: Bad Request / Missing Field
        '401':
          description: Unauthorized
        '415':
          description: Unsupported Media Type
        '500':
          description: Internal Server Error
      x-documentation:
        routeExamples:
          Basic usage:
            value: /subscriptions/users
          Paging:
            value: /subscriptions/users?Page=6&PageSize=2
          Using a continuation token:
            value: /subscriptions/users?ContinuationToken=262145
        curlExamples:
          All users across all subscriptions, with default paging - cURL:
            description: /subscriptions/users
            value: '{}'
          Subset of users defined by page and size, with all their subscriptions - cURL:
            description: /subscriptions/users?Page=2&PageSize=2
            value: '{}'
  /1.0/subscriptions/{SubscriptionID}/users/{UserID}/roles:
    put:
      tags:
      - Subscription Users
      summary: Update Subscription User Roles
      description: This request allows you to modify the roles of an existing subscription user. <p> Note that the subscription owner, added during <b>Add Subscription</b>, must have the Admin role. You will receive a 403 Forbidden if you try to remove it. </p>
      parameters:
      - name: SubscriptionID
        in: path
        description: Your reference for the subscription. This is the same ID you specified, or was automatically generated, when the subscription was created, i.e., when calling <b>Add Subscription</b>.
        required: true
        schema:
          type: string
      - name: UserID
        in: path
        description: Your reference for the user. This is the same ID you specified, or was automatically generated, when the subscription was created i.e., when calling <b>Add Subscription</b>, or when adding a user through <b>Add Subscription User</b>.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSubscriptionUserRoles'
            examples:
              Basic usage:
                value: '{"Roles":["Admin","Editor"]}'
      responses:
        '204':
          description: No Content
        '400':
          description: Bad Request / Missing Field
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '415':
          description: Unsupported Media Type
        '500':
          description: Internal Server Error
      x-documentation:
        curlExamples:
          Basic usage - cURL:
            description: /subscriptions/EX-Subscription-001/users/{UserID}/roles
            value: '{"Roles":["Admin"]}'
components:
  schemas:
    AddSubscriptionUser:
      title: AddSubscriptionUserRequest
      required:
      - UserID
      - EmailAddress
      - Roles
      properties:
        UserID:
          type: string
          description: Your reference for the user. Must only contain upper case letters, lower case letters, numbers, '-' and '_'.
        EmailAddress:
          type: string
          description: The email address of the user.
        Roles:
          type: array
          items:
            type: string
          description: The roles you wish to user to have. The user must be assigned a role, but can have one or both. <p> Admin - Has full control over signatures and settings<br /> Editor - Can create/edit and re-order signatures for permitted folders </p> Roles are not case-sensitive.
        SendWelcomeEmailToCustomer:
          type: boolean
          description: Specifies whether an email will be sent to the customer asking them to login for the first time, or informing them they have been added to the subscription. This defaults to true.
      description: This request allows you to add new users to a subscription. <p> The same user can be added to multiple subscriptions. </p><p> Note that you cannot modify an existing subscription user with this API. However, if the user has previously been deleted, they can be re-added. </p>
    SubscriptionUsersResponse:
      title: SubscriptionUsersResponse
      properties:
        Users:
          type: array
          items:
            $ref: '#/components/schemas/SubscriptionUser'
          description: If there are more users than the <b>PageSize</b>, then this will contain a subset of all users.
        UserCount:
          type: number
          description: The total number of users available. This is useful for when the number of users is greater than the current page size.
          format: int32
    UpdateSubscriptionUserRoles:
      title: UpdateSubscriptionUserRolesRequest
      required:
      - Roles
      properties:
        Roles:
          type: array
          items:
            type: string
          description: The roles you wish to user to have. The user must be assigned a role, but can have one or both. <p> Admin - Has full control over signatures and settings<br /> Editor - Can create/edit and re-order signatures for permitted folders </p> Roles are not case-sensitive.
      description: This request allows you to modify the roles of an existing subscription user. <p> Note that the subscription owner, added during <b>Add Subscription</b>, must have the Admin role. You will receive a 403 Forbidden if you try to remove it. </p>
    DistributorLevelSubscriptionUserInfo:
      title: UserSubscriptionDetails
      properties:
        SubscriptionID:
          type: string
          description: Your reference to the subscription. This is the same ID you specified when the subscription was create via <b>Add Subscription</b>.
        UserID:
          type: string
          description: Your reference for the user. This is the same ID you specified, or was automatically generated, when the subscription was created i.e., when calling <b>Add Subscription</b>, or when adding a user through <b>Add Subscription User</b>. <p> The same user can have a different UserID for each subscription. </p><p> If the user was not created via the Cloud API, then this value will not be returned. This means that although you can view their details, you will not be able to reference this user when making calls to the Cloud API. </p>
        Roles:
          type: array
          items:
            type: string
          description: The same user can have different roles for each subscription. <p> Admin<br /> Editor </p>
    DistributorLevelSubscriptionUsersResponse:
      title: DistributorLevelSubscriptionUsersResponse
      properties:
        Users:
          type: array
          items:
            $ref: '#/components/schemas/DistributorLevelSubscriptionUser'
          description: If there are more users than the <b>PageSize</b>, then this will contain a subset of all users.
        UserCount:
          type: number
          description: The total number of users available. This is useful for when the number users is greater than the current page size.
          format: int32
        ContinuationToken:
          type: number
          description: See the section <b>"Paging of results"</b> at the beginning of the document.
          format: int32
        Page:
          type: number
          description: See the section <b>"Paging of results"</b> at the beginning of the document.
          format: int32
        PageSize:
          type: number
          description: See the section <b>"Paging of results"</b> at the beginning of the document.
          format: int32
    SubscriptionUser:
      title: SubscriptionUser
      properties:
        Email:
          type: string
        UserID:
          type: string
          description: Your reference for the user. This is the same ID you specified, or was automatically generated, when the subscription was created i.e., when calling <b>Add Subscription</b>, or when adding a user through <b>Add Subscription User</b>. <p> If the user was not created via the Cloud API, then this value will not be returned. This means that although you can view their details, you will not be able to reference this user when making calls to the Cloud API. </p>
        Roles:
          type: array
          items:
            type: string
          description: Admin<br /> Editor
    DistributorLevelSubscriptionUser:
      title: User
      properties:
        Email:
          type: string
          description: Email address of the user.
        Subscriptions:
          type: array
          items:
            $ref: '#/components/schemas/DistributorLevelSubscriptionUserInfo'
          description: The subscriptions the user is a member of.
  securitySchemes:
    Exclaimer:
      type: apiKey
      name: ExApiToken
      in: header