Extole Users API

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 Users 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: Users
paths:
  /v2/users:
    get:
      description: Returns all staff user accounts with access to the Extole console. Use the `scope` query parameter to restrict results to the current account or retrieve all accessible users.
      operationId: listUsers
      parameters:
      - description: 'accepts values: ''account''|''all'''
        in: query
        name: scope
        schema:
          default: account
          nullable: true
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/UserResponse'
                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 users
      tags:
      - Users
      x-extole-bundle: management
      x-extole-visibility: visible
    post:
      description: Creates a new staff user account with access to the Extole console. Returns the created user with its server-assigned id. An invitation email is sent to the new user.
      operationId: createUser
      requestBody:
        content:
          application/json:
            example:
              email: email
              first_name: first_name
              last_name: last_name
              password: password
              scopes:
              - CLIENT_ADMIN
            schema:
              $ref: '#/components/schemas/UserCreationRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                common_password:
                  $ref: '#/components/examples/common_password'
                duplicate_user:
                  $ref: '#/components/examples/duplicate_user'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                invalid_password_change_limit:
                  $ref: '#/components/examples/invalid_password_change_limit'
                invalid_password_length:
                  $ref: '#/components/examples/invalid_password_length'
                invalid_password_strength_letters_digits:
                  $ref: '#/components/examples/invalid_password_strength_letters_digits'
                invalid_password_strength_letters_digits_punctuation:
                  $ref: '#/components/examples/invalid_password_strength_letters_digits_punctuation'
                invalid_user_email:
                  $ref: '#/components/examples/invalid_user_email'
                invalid_user_first_name:
                  $ref: '#/components/examples/invalid_user_first_name'
                invalid_user_last_name:
                  $ref: '#/components/examples/invalid_user_last_name'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
                password_already_used:
                  $ref: '#/components/examples/password_already_used'
                unauthorized_scope:
                  $ref: '#/components/examples/unauthorized_scope'
                user_scopes_missing:
                  $ref: '#/components/examples/user_scopes_missing'
                user_self_scopes_update:
                  $ref: '#/components/examples/user_self_scopes_update'
              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'
                account_disabled:
                  $ref: '#/components/examples/account_disabled'
                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
      tags:
      - Users
      x-extole-bundle: management
      x-extole-visibility: visible
  /v2/users/{userId}:
    get:
      description: Returns the staff user account for the specified id.
      operationId: getUser
      parameters:
      - in: path
        name: userId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
          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: Get a user
      tags:
      - Users
      x-extole-bundle: management
      x-extole-visibility: visible
    put:
      description: Updates the staff user account. Only fields present in the request body are changed. Returns the updated user.
      operationId: updateUser
      parameters:
      - in: path
        name: userId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              email: email
              first_name: first_name
              last_name: last_name
              password: password
              scopes:
              - CLIENT_ADMIN
            schema:
              $ref: '#/components/schemas/UserUpdateRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserResponse'
          description: Successful response
        '400':
          content:
            application/json:
              examples:
                binding_error:
                  $ref: '#/components/examples/binding_error'
                common_password:
                  $ref: '#/components/examples/common_password'
                duplicate_user:
                  $ref: '#/components/examples/duplicate_user'
                invalid_json:
                  $ref: '#/components/examples/invalid_json'
                invalid_parameter:
                  $ref: '#/components/examples/invalid_parameter'
                invalid_password_change_limit:
                  $ref: '#/components/examples/invalid_password_change_limit'
                invalid_password_length:
                  $ref: '#/components/examples/invalid_password_length'
                invalid_password_strength_letters_digits:
                  $ref: '#/components/examples/invalid_password_strength_letters_digits'
                invalid_password_strength_letters_digits_punctuation:
                  $ref: '#/components/examples/invalid_password_strength_letters_digits_punctuation'
                invalid_user_email:
                  $ref: '#/components/examples/invalid_user_email'
                invalid_user_first_name:
                  $ref: '#/components/examples/invalid_user_first_name'
                invalid_user_id:
                  $ref: '#/components/examples/invalid_user_id'
                invalid_user_last_name:
                  $ref: '#/components/examples/invalid_user_last_name'
                missing_request_body:
                  $ref: '#/components/examples/missing_request_body'
                password_already_used:
                  $ref: '#/components/examples/password_already_used'
                unauthorized_scope:
                  $ref: '#/components/examples/unauthorized_scope'
                user_scopes_missing:
                  $ref: '#/components/examples/user_scopes_missing'
                user_self_scopes_update:
                  $ref: '#/components/examples/user_self_scopes_update'
              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'
                account_disabled:
                  $ref: '#/components/examples/account_disabled'
                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
      tags:
      - Users
      x-extole-bundle: management
      x-extole-visibility: visible
    delete:
      description: Deactivates and removes the staff user account, revoking all console access.
      operationId: deleteUser
      parameters:
      - in: path
        name: userId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
          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: Delete a user
      tags:
      - Users
      x-extole-bundle: management
      x-extole-visibility: visible
  /v2/users/{user_id}/properties:
    get:
      description: Returns all per-user property overrides for the specified staff user.
      operationId: listUserProperties
      parameters:
      - in: path
        name: user_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/PropertyResponse'
                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 properties
      tags:
      - Users
      x-extole-bundle: management
      x-extole-visibility: visible
    post:
      description: Creates a new per-user property override for the specified staff user. Returns the created property.
      operationId: createUserProperty
      parameters:
      - in: path
        name: user_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              name: name
              value: value
            schema:
              $ref: '#/components/schemas/PropertyCreationRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PropertyResponse'
          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'
                use_legacy_label_targeting_client_property_is_only_supported_with_targeting_v3:
                  $ref: '#/components/examples/use_legacy_label_targeting_client_property_is_only_supported_with_targeting_v3'
              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_property:
                  $ref: '#/components/examples/duplicate_property'
                invalid_length_name:
                  $ref: '#/components/examples/invalid_length_name'
                invalid_length_value:
                  $ref: '#/components/examples/invalid_length_value'
                invalid_name:
                  $ref: '#/components/examples/invalid_name'
                invalid_scope:
                  $ref: '#/components/examples/invalid_scope'
                method_unauthorized:
                  $ref: '#/components/examples/method_unauthorized'
                missing_access_token:
                  $ref: '#/components/examples/missing_access_token'
                null_value:
                  $ref: '#/components/examples/null_value'
              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 property
      tags:
      - Users
      x-extole-bundle: management
      x-extole-visibility: visible
  /v2/users/{user_id}/properties/{name}:
    get:
      description: Returns the per-user property override for the specified user and property name.
      operationId: getUserProperty
      parameters:
      - in: path
        name: user_id
        required: true
        schema:
          type: string
      - in: path
        name: name
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PropertyResponse'
          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_name:
                  $ref: '#/components/examples/invalid_name'
                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 property
      tags:
      - Users
      x-extole-bundle: management
      x-extole-visibility: visible
    put:
      description: Updates the per-user property override for the specified staff user and property name. Returns the updated property.
      operationId: updateUserProperty
      parameters:
      - in: path
        name: user_id
        required: true
        schema:
          type: string
      - in: path
        name: name
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
              value: value
            schema:
              $ref: '#/components/schemas/PropertyUpdateRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PropertyResponse'
          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'
                use_legacy_label_targeting_client_property_is_only_supported_with_targeting_v3:
                  $ref: '#/components/examples/use_legacy_label_targeting_client_property_is_only_supported_with_targeting_v3'
              schema:
                $ref: '#/co

# --- truncated at 32 KB (65 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/extole/refs/heads/main/openapi/extole-users-api-openapi.yml