API Evangelist conversational phrasing for Zendesk Users API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Zendesk Users API
  version: 1.0.0
extends: openapi/zendesk-users-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 30
- target: $.paths['/api/v2/users/autocomplete'].get
  update:
    x-apievangelist-phrasing:
      intent: Autocomplete users by the start of their name
      effect: read
      questions:
      - Can I get user suggestions as someone types the first letters of a name?
      - Which users have a name beginning with a given prefix, excluding ones with foreign identities?
      instructions:
      - text: Suggest users whose names start with {name}.
        slots:
          name: query.name
      - text: Autocomplete the user name prefix {name} for my ticket form.
        slots:
          name: query.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/deleted_users'].get
  update:
    x-apievangelist-phrasing:
      intent: List deleted users
      effect: read
      questions:
      - Where can I see every user that has been deleted from my Zendesk account?
      - Does the deleted users list include people who were permanently deleted?
      instructions:
      - text: List all the users that have been deleted, including permanently deleted ones.
      - text: Show me the deleted user records in the account.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/deleted_users/{deleted_user_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Show a soft-deleted user
      effect: read
      questions:
      - Can I look up the details of one user that was deleted but not yet permanently removed?
      - What does a single soft-deleted user record still contain?
      instructions:
      - text: Fetch the record of a single deleted user who has not been permanently removed yet.
      - text: Pull up one soft-deleted user's details by their deleted user ID.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/deleted_users/{deleted_user_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Permanently delete a deleted user
      effect: destructive
      questions:
      - How do I permanently erase a user's personal data after they have already been deleted?
      - Is permanently deleting a user reversible?
      instructions:
      - text: Permanently erase a user I already soft-deleted, including all their info.
      - text: Purge a previously deleted user for good to meet a GDPR erasure request.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/deleted_users/count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count deleted users
      effect: read
      questions:
      - How many users have been deleted from my account so far?
      - How fresh is the deleted user count when there are more than 100,000?
      instructions:
      - text: Give me the approximate number of deleted users.
      - text: Count the deleted users and tell me when that count was last refreshed.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/users/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search users by query or external ID
      effect: read
      questions:
      - Can I search the agents and end users in my help desk with a search query?
      - What is the maximum number of users a single user search can return?
      - Is there a way to find a user by their external ID from my own system?
      instructions:
      - text: Search users in the api/v2 user search for {query}.
        slots:
          query: query.query
      - text: Find the user whose external ID is {external_id}.
        slots:
          external_id: query.external_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List all users in the account
      effect: read
      questions:
      - What is the recommended way to page through every user in my account?
      - How many users does each page of the api/v2 user list return?
      instructions:
      - text: List every user in the account using cursor pagination.
      - text: Page through all users from the v2 users endpoint, 100 at a time.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/users'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a user
      effect: write
      questions:
      - How do I add a new single user through the api/v2 users endpoint?
      - Can I create an agent or end user record from my own signup flow?
      instructions:
      - text: Create a new user record via the v2 users endpoint.
      - text: Add one new end user to my Zendesk account.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/users/{user_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Show a user
      effect: read
      questions:
      - Can I fetch the full profile of one user from the v2 API by their ID?
      - What details does the v2 show-user call return for an agent?
      instructions:
      - text: Show the v2 profile for user {user_id}.
        slots:
          user_id: path.user_id
      - text: Look up user {user_id} through api/v2.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/users/{user_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a user
      effect: write
      questions:
      - Can I change an existing user's details through the v2 users endpoint?
      - Which call edits a single user record under api/v2?
      instructions:
      - text: Update user {user_id} through the v2 users endpoint.
        slots:
          user_id: path.user_id
      - text: Edit the v2 record of user {user_id}.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/users/{user_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user and associated records
      effect: destructive
      questions:
      - What happens to a user's associated records when I delete them via api/v2?
      - Can a user deleted through the v2 endpoint be recovered?
      instructions:
      - text: Delete user {user_id} and their associated records via api/v2.
        slots:
          user_id: path.user_id
      - text: Remove user {user_id} from the account using the v2 delete call.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/users/{user_id}/compliance_deletion_statuses'].get
  update:
    x-apievangelist-phrasing:
      intent: Show a user's GDPR deletion status
      effect: read
      questions:
      - How can I check whether a user's GDPR deletion has finished in each product area?
      - Can I see the compliance deletion status for just one area such as support/explore?
      instructions:
      - text: Show the compliance deletion statuses for user {user_id}.
        slots:
          user_id: path.user_id
      - text: Check the GDPR deletion status of user {user_id} in the {application} area.
        slots:
          user_id: path.user_id
          application: query.application
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/users/{user_id}/merge'].put
  update:
    x-apievangelist-phrasing:
      intent: Merge two end users
      effect: destructive
      questions:
      - Can I merge a duplicate end user account into another end user?
      - Why would merging an end user with more than 10,000 requested tickets be blocked?
      instructions:
      - text: Merge end user {user_id} into the other end user I specify.
        slots:
          user_id: path.user_id
      - text: Combine duplicate end user {user_id} with their existing account.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/users/{user_id}/related'].get
  update:
    x-apievangelist-phrasing:
      intent: Show a user's related information
      effect: read
      questions:
      - Where can I get the related info summary for a user, such as their ticket counts?
      - Is there a call that returns data related to a user rather than the profile itself?
      instructions:
      - text: Show the related information for user {user_id}.
        slots:
          user_id: path.user_id
      - text: Get the related-records summary of user {user_id}.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/users/count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count users
      effect: read
      questions:
      - How many users are in my account in total?
      - When was the approximate user count last refreshed?
      instructions:
      - text: Give me the approximate total number of users.
      - text: Count the users in the account.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/users/create_many'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk create up to 100 users
      effect: write
      questions:
      - Can I import a batch of users in a single request?
      - Why would a bulk user import be rejected when it isn't enabled on my account?
      instructions:
      - text: Bulk import this array of up to 100 new users.
      - text: Create many users at once as a background job.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/users/create_or_update'].post
  update:
    x-apievangelist-phrasing:
      intent: Create or update a user by email or external ID
      effect: write
      questions:
      - Can I upsert a user so it is created if missing or updated if the email already exists?
      - What role does a new user get from create-or-update if I leave the role out?
      instructions:
      - text: Upsert a single user matched by email address or external ID.
      - text: Create this user, or update them if they already exist.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/users/create_or_update_many'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk create or update up to 100 users
      effect: write
      questions:
      - Is there a bulk upsert for a list of users?
      - What limit applies when syncing many users so each is created or updated?
      instructions:
      - text: Sync this array of up to 100 users, creating the new ones and updating the rest.
      - text: Bulk upsert many users from my CRM export.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/users/destroy_many'].delete
  update:
    x-apievangelist-phrasing:
      intent: Bulk delete up to 100 users
      effect: destructive
      questions:
      - Can I delete a whole list of users at once?
      - Does the bulk user delete accept external IDs instead of Zendesk IDs?
      instructions:
      - text: Delete the users with IDs {ids} in bulk.
        slots:
          ids: query.ids
      - text: Bulk delete the users whose external IDs are {external_ids}.
        slots:
          external_ids: query.external_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/users/logout_many'].post
  update:
    x-apievangelist-phrasing:
      intent: Log out many users
      effect: write
      questions:
      - Can an admin force several users to sign out at the same time?
      - How many users can be logged out in one request?
      instructions:
      - text: Sign out the users {ids} from all their sessions.
        slots:
          ids: query.ids
      - text: 'Force-logout this comma-separated list of user IDs: {ids}.'
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/users/me'].get
  update:
    x-apievangelist-phrasing:
      intent: Show the currently signed-in user
      effect: read
      questions:
      - Who am I authenticated as when I call the API?
      - Where do I get the authenticity token for requests made by end users?
      instructions:
      - text: Show the user I'm authenticated as, with the authenticity token.
      - text: Tell me which account my current credentials belong to.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/users/request_create'].post
  update:
    x-apievangelist-phrasing:
      intent: Ask the owner to add agent seats
      effect: write
      questions:
      - Can an agent nudge the account owner to upgrade so more agents can be created?
      - What does the request-create call send to the account owner?
      instructions:
      - text: Email the account owner a reminder to update the subscription for more agents.
      - text: Request more agent seats from the owner.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/users/show_many'].get
  update:
    x-apievangelist-phrasing:
      intent: Show many users by ID
      effect: read
      questions:
      - Can I fetch several specific users in one call?
      - What is the maximum number of IDs I can pass when retrieving multiple users?
      instructions:
      - text: Retrieve the users with IDs {ids}.
        slots:
          ids: query.ids
      - text: Get the user records for external IDs {external_ids}.
        slots:
          external_ids: query.external_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/users/update_many'].put
  update:
    x-apievangelist-phrasing:
      intent: Bulk update users
      effect: write
      questions:
      - Can I apply the same change to a list of users in one request?
      - Does bulk user update let me target users by their external IDs?
      instructions:
      - text: Apply this update to users {ids}.
        slots:
          ids: query.ids
      - text: Bulk update the users with external IDs {external_ids}.
        slots:
          external_ids: query.external_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users'].get
  update:
    x-apievangelist-phrasing:
      intent: List users filtered by role or permission set
      effect: read
      questions:
      - Can I list only the admins, agents or end users in the account?
      - Which users are assigned a particular custom permission set?
      instructions:
      - text: List users with the {role} role.
        slots:
          role: query.role
      - text: Show users in permission set {permission_set}, {per_page} per page.
        slots:
          permission_set: query.permission_set
          per_page: query.per_page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a user with name and email or phone
      effect: write
      questions:
      - What is the minimum I must provide to create a user, a name plus email or phone?
      - Does a newly created user default to the end-user role?
      instructions:
      - text: Create the user described by {user}.
        slots:
          user: requestBody.user
      - text: Register {user} as a new end user with a name and phone number.
        slots:
          user: requestBody.user
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a user's details
      effect: read
      questions:
      - Where can I read the details of a specific person on the /users path?
      - Can I retrieve one customer's record to see their role and organization?
      instructions:
      - text: Get the details for user {user_id}.
        slots:
          user_id: path.user_id
      - text: Retrieve customer {user_id}'s role and organization.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Change a user's name, email, role or tags
      effect: write
      questions:
      - Can I change a user's role, organization, tags or custom fields?
      - Which properties of a person can I modify, such as their email?
      instructions:
      - text: Set user {user_id}'s properties to {user}.
        slots:
          user_id: path.user_id
          user: requestBody.user
      - text: Change the role and tags of user {user_id} to what's in {user}.
        slots:
          user_id: path.user_id
          user: requestBody.user
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/{user_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Soft-delete a user
      effect: destructive
      questions:
      - Can a soft-deleted user be recovered within a limited time?
      - Who is allowed to delete agents and admins?
      instructions:
      - text: Soft-delete user {user_id}.
        slots:
          user_id: path.user_id
      - text: Remove person {user_id} so they can still be restored for a while.
        slots:
          user_id: path.user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/users/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search users by name, email or external ID
      effect: read
      questions:
      - Can I look people up by name or email address and page through matches?
      - How can I control how many matching people come back per page?
      instructions:
      - text: Look up people matching {query}.
        slots:
          query: query.query
      - text: Find users by email {query}, page {page}.
        slots:
          query: query.query
          page: query.page
      method: generated
      generated: '2026-09-26'