# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Users.user API
  version: 1.0.0
extends: openapi/azure-ad-users-user-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: 9
- target: $.paths['/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List users in the directory
      effect: read
      questions:
      - How do I pull a list of every user account in my Entra ID tenant?
      - Can I search users by display name, and does that need the ConsistencyLevel header?
      - Which users are in the Sales department?
      instructions:
      - text: List the users in my directory.
      - text: Find users whose name matches {search}, sending ConsistencyLevel {consistency}.
        slots:
          search: query.$search
          consistency: header.ConsistencyLevel
      - text: List users filtered by {filter}, sorted by {orderby}.
        slots:
          filter: query.$filter
          orderby: query.$orderby
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new user account
      effect: write
      questions:
      - What's the minimum I need to supply to create a new employee account?
      - Can I set an initial password and force a change at first sign-in when I add a user?
      instructions:
      - text: Create user {display_name} with sign-in name {upn} and mail nickname {mail_nickname}.
        slots:
          display_name: requestBody.displayName
          upn: requestBody.userPrincipalName
          mail_nickname: requestBody.mailNickname
      - text: Add a new enabled account for {display_name} as {upn} with password profile {password_profile}.
        slots:
          display_name: requestBody.displayName
          upn: requestBody.userPrincipalName
          password_profile: requestBody.passwordProfile
      - text: Onboard a new hire named {display_name}, job title {job_title}, in department {department}, sign-in {upn}.
        slots:
          display_name: requestBody.displayName
          job_title: requestBody.jobTitle
          department: requestBody.department
          upn: requestBody.userPrincipalName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user by object id
      effect: read
      questions:
      - How do I look up a single user's properties from their object id?
      - Why aren't all user properties returned by default, and how do I request extra ones?
      instructions:
      - text: Get user {user_id} by object id.
        slots:
          user_id: path.user-id
      - text: Show {fields} for the user with id {user_id}.
        slots:
          fields: query.$select
          user_id: path.user-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user by object id
      effect: destructive
      questions:
      - What happens to a user's mailbox and licenses when I delete their account?
      - Can a deleted user still be restored within 30 days?
      instructions:
      - text: Delete the user whose object id is {user_id}.
        slots:
          user_id: path.user-id
      - text: Offboard user id {user_id} by deleting the account.
        slots:
          user_id: path.user-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/{user-id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a user by object id
      effect: write
      questions:
      - How do I change a user's job title or department using their object id?
      - Can I disable sign-in for an account without deleting it?
      instructions:
      - text: Set the job title of user id {user_id} to {job_title}.
        slots:
          user_id: path.user-id
          job_title: requestBody.jobTitle
      - text: Disable sign-in for user id {user_id} by setting accountEnabled to {enabled}.
        slots:
          user_id: path.user-id
          enabled: requestBody.accountEnabled
      - text: Move user id {user_id} to department {department} and office {office}.
        slots:
          user_id: path.user-id
          department: requestBody.department
          office: requestBody.officeLocation
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users(userPrincipalName=\'{userPrincipalName}\')'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user by sign-in name
      effect: read
      questions:
      - Can I fetch a user directly by their userPrincipalName instead of the object id?
      - What's the way to look up someone when all I know is their sign-in email address?
      instructions:
      - text: Get the user whose sign-in name is {upn}.
        slots:
          upn: path.userPrincipalName
      - text: Look up {upn} by user principal name and show {fields}.
        slots:
          upn: path.userPrincipalName
          fields: query.$select
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users(userPrincipalName=\'{userPrincipalName}\')'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user by sign-in name
      effect: destructive
      questions:
      - Is it possible to delete an account addressed by userPrincipalName rather than id?
      - If I remove a user by their sign-in name, are they still recoverable for a month?
      instructions:
      - text: Delete the account with user principal name {upn}.
        slots:
          upn: path.userPrincipalName
      - text: Remove {upn} from the directory using their sign-in name.
        slots:
          upn: path.userPrincipalName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users(userPrincipalName=\'{userPrincipalName}\')'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a user by sign-in name
      effect: write
      questions:
      - Can I patch a user's profile when I only have their userPrincipalName?
      - How do I change someone's mobile number addressing them by sign-in name?
      instructions:
      - text: Set the mobile phone for {upn} to {mobile}, addressing them by user principal name.
        slots:
          upn: path.userPrincipalName
          mobile: requestBody.mobilePhone
      - text: Update the display name of sign-in name {upn} to {display_name}.
        slots:
          upn: path.userPrincipalName
          display_name: requestBody.displayName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/users/$count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count users in the directory
      effect: read
      questions:
      - How many user accounts does my tenant have?
      - What's the count of guest users, and is the ConsistencyLevel header needed for it?
      instructions:
      - text: Count all users in the directory.
      - text: Count users matching {filter} with ConsistencyLevel {consistency}.
        slots:
          filter: query.$filter
          consistency: header.ConsistencyLevel
      method: generated
      generated: '2026-10-01'