API Evangelist conversational phrasing for User Management User Admin API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for User Management User Admin API
  version: 1.0.0
extends: openapi/conga-user-admin-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 21
- target: $.paths['/api/user-management/v1/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List users in the organization
      effect: read
      questions:
      - Can I list every user in my Conga platform tenant?
      - Which users match a criteria filter, sorted by last name?
      - Is the user directory paged, and how big can a page be?
      instructions:
      - text: List all users matching {criteria}.
        slots:
          criteria: query.criteria
      - text: Show page {pageNumber} of users, {pageSize} per page, sorted by {sortField}.
        slots:
          pageNumber: query.pageNumber
          pageSize: query.pageSize
          sortField: query.sortField
      - text: Give me the full user list in {sortDirection} order.
        slots:
          sortDirection: query.sortDirection
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/users'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a single user
      effect: write
      questions:
      - How do I add one new user with a name, email and role?
      - Can I set a new user's time zone and currency when I create them?
      instructions:
      - text: Create a user {FirstName} {LastName} with email {Email}.
        slots:
          FirstName: requestBody.FirstName
          LastName: requestBody.LastName
          Email: requestBody.Email
      - text: Add one new user with username {UserName} and role {Role}.
        slots:
          UserName: requestBody.UserName
          Role: requestBody.Role
      - text: Set up a new user {Email} in time zone {Timezone} with currency {Currency}.
        slots:
          Email: requestBody.Email
          Timezone: requestBody.Timezone
          Currency: requestBody.Currency
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/users/bulk'].post
  update:
    x-apievangelist-phrasing:
      intent: Create many new users in one request
      effect: write
      questions:
      - Can I create a batch of brand-new users in a single call?
      - What happens in bulk creation if one of the users already exists?
      - Is bulk user creation allowed for integration users?
      instructions:
      - text: Create these new users in bulk and return their IDs.
      - text: Bulk-create the user accounts in this list, flagging any that already exist.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/users/bulk'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update many existing users at once
      effect: write
      questions:
      - Can I patch fields on a whole batch of existing users together?
      - Are integration users excluded from bulk user updates?
      instructions:
      - text: Apply these field changes to the existing users in bulk.
      - text: Bulk-update the listed users' details without creating anyone new.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/users/bulk-upsert'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or update many users asynchronously
      effect: write
      questions:
      - Is there an upsert that updates existing users and creates missing ones in one go?
      - Does the bulk upsert avoid duplicate user records?
      instructions:
      - text: Upsert this batch of users, updating matches and creating the rest.
      - text: Run a bulk user upsert in the background for this list.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/users/bulk-upsert-sync'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or update many users synchronously
      effect: write
      questions:
      - Can I run a user upsert that waits and returns all IDs in the same response?
      - Which upsert call gives me results synchronously instead of queuing?
      instructions:
      - text: Synchronously upsert these users and wait for their IDs.
      - text: Do a blocking bulk upsert of this user list and return the results now.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/users/templates/download'].get
  update:
    x-apievangelist-phrasing:
      intent: Download the CSV template for user upload
      effect: read
      questions:
      - Where do I get the CSV template with all user fields for importing users?
      - What columns does the user upload file need?
      instructions:
      - text: Download the latest user upload CSV template.
      - text: Generate the blank user-import spreadsheet with every user field.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/users/upload'].post
  update:
    x-apievangelist-phrasing:
      intent: Import users from a CSV file
      effect: write
      questions:
      - How do I import users from a CSV file?
      - Does the CSV user import validate rows before creating accounts?
      instructions:
      - text: Upload {usersDataFile} and create the users in it.
        slots:
          usersDataFile: requestBody.usersDataFile
      - text: Import user records from the CSV file {usersDataFile}.
        slots:
          usersDataFile: requestBody.usersDataFile
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/users/{integrationUserId}/secret'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up an integration user's client ID
      effect: read
      questions:
      - Where can I find the OAuth client ID for an integration user?
      - Can I read an integration user's client ID without generating a new secret?
      instructions:
      - text: Get the client ID for integration user {integrationUserId}.
        slots:
          integrationUserId: path.integrationUserId
      - text: Look up which client ID belongs to integration user {integrationUserId}.
        slots:
          integrationUserId: path.integrationUserId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/users/{integrationUserId}/secret'].patch
  update:
    x-apievangelist-phrasing:
      intent: Generate a client secret for an integration user
      effect: write
      questions:
      - How do I generate a client secret for an integration user?
      - Can I issue fresh client credentials for a service account?
      instructions:
      - text: Generate a new client secret for integration user {integrationUserId}.
        slots:
          integrationUserId: path.integrationUserId
      - text: Issue client ID and secret credentials for integration user {integrationUserId}.
        slots:
          integrationUserId: path.integrationUserId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/users/{userId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's details
      effect: read
      questions:
      - What profile details are stored for a specific user?
      - Can I fetch one user's record by their user ID?
      instructions:
      - text: Show the details for user {userId}.
        slots:
          userId: path.userId
      - text: Fetch the full profile of user {userId}.
        slots:
          userId: path.userId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/users/{userId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Deactivate a user
      effect: destructive
      questions:
      - How do I deactivate a user who has left the company?
      - Does removing a user delete them or just deactivate the account?
      instructions:
      - text: Deactivate user {userId}.
        slots:
          userId: path.userId
      - text: Turn off the account for user {userId} so they can no longer sign in.
        slots:
          userId: path.userId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/users/{userId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update one user's profile
      effect: write
      questions:
      - Can I change a single user's email, role or locale formats?
      - Is there a way to suspend one user by editing their profile?
      - Which call edits the date and currency display formats for a specific user?
      instructions:
      - text: Change user {userId}'s email to {Email}.
        slots:
          userId: path.userId
          Email: requestBody.Email
      - text: 'Set user {userId} as suspended: {IsSuspended}.'
        slots:
          userId: path.userId
          IsSuspended: requestBody.IsSuspended
      - text: Update user {userId}'s short date format to {LocaleShortDateFormat}.
        slots:
          userId: path.userId
          LocaleShortDateFormat: requestBody.LocaleShortDateFormat
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/users/{userId}/clone'].post
  update:
    x-apievangelist-phrasing:
      intent: Clone an existing user
      effect: write
      questions:
      - Can I copy an existing user's setup to onboard someone new?
      - Is cloning supported for integration users?
      instructions:
      - text: Clone user {userId} as new username {UserName}.
        slots:
          userId: path.userId
          UserName: requestBody.UserName
      - text: Make a copy of user {userId} with external ID {ExternalId}.
        slots:
          userId: path.userId
          ExternalId: requestBody.ExternalId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/users/{userId}/permissiongroups'].put
  update:
    x-apievangelist-phrasing:
      intent: Add permission groups to a user
      effect: write
      questions:
      - How do I give a user an extra permission group?
      - Does assigning a permission group replace the user's current groups or append?
      instructions:
      - text: Add permission groups {PermissionGroupNames} to user {userId}.
        slots:
          PermissionGroupNames: requestBody.PermissionGroupNames
          userId: path.userId
      - text: Grant user {userId} membership in permission group {PermissionGroupNames}.
        slots:
          userId: path.userId
          PermissionGroupNames: requestBody.PermissionGroupNames
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/users/{userId}/permissiongroups'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove permission groups from a user
      effect: destructive
      questions:
      - Can I take a permission group away from a user?
      - What errors come back if a permission group I remove isn't on the user?
      instructions:
      - text: Remove permission groups {PermissionGroupNames} from user {userId}.
        slots:
          PermissionGroupNames: requestBody.PermissionGroupNames
          userId: path.userId
      - text: Revoke user {userId}'s membership in {PermissionGroupNames}.
        slots:
          userId: path.userId
          PermissionGroupNames: requestBody.PermissionGroupNames
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/users/{userId}/restore'].put
  update:
    x-apievangelist-phrasing:
      intent: Reactivate a deactivated user
      effect: write
      questions:
      - Can I bring back a user account that was deactivated?
      - How do I restore access for someone who was turned off by mistake?
      instructions:
      - text: Restore deactivated user {userId}.
        slots:
          userId: path.userId
      - text: Reactivate the account of user {userId}.
        slots:
          userId: path.userId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/users/{userId}/roles'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's role
      effect: read
      questions:
      - Which role is a particular user assigned?
      - What's the role name on a given user's account?
      instructions:
      - text: Tell me what role user {userId} has.
        slots:
          userId: path.userId
      - text: Look up the role name assigned to user {userId}.
        slots:
          userId: path.userId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/users/{userId}/roles/{roleId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Change a user's role
      effect: write
      questions:
      - Can I move a user to a different role?
      - Which call reassigns someone's role by role ID?
      instructions:
      - text: Change user {userId}'s role to {roleId}.
        slots:
          userId: path.userId
          roleId: path.roleId
      - text: Assign role {roleId} to user {userId}, replacing their current role.
        slots:
          roleId: path.roleId
          userId: path.userId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/users/{userId}/roles/{roleId}/exists'].get
  update:
    x-apievangelist-phrasing:
      intent: Check whether a user holds a role
      effect: read
      questions:
      - Is a specific user assigned a particular role, yes or no?
      - Can I verify a user has an admin role before granting access?
      instructions:
      - text: Check if user {userId} is assigned role {roleId}.
        slots:
          userId: path.userId
          roleId: path.roleId
      - text: Confirm whether role {roleId} belongs to user {userId}.
        slots:
          roleId: path.roleId
          userId: path.userId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/user-management/v1/users/{userId}/send-welcome-email'].post
  update:
    x-apievangelist-phrasing:
      intent: Re-send a new user's welcome email
      effect: write
      questions:
      - A new user never got their welcome email with login details; can I send it again?
      - Can I resend login credentials after fixing a user's email address?
      instructions:
      - text: Re-send the welcome email to user {userId}.
        slots:
          userId: path.userId
      - text: Email the login details again to new user {userId}.
        slots:
          userId: path.userId
      method: generated
      generated: '2026-10-01'