# 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 User Identities API
  version: 1.0.0
extends: openapi/zendesk-user-identities-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: 8
- target: $.paths['/api/v2/users/{user_id}/identities'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's identities
      effect: read
      questions:
      - Which emails, phone numbers and social accounts are attached to a user?
      - Can I list only the email identities of a user?
      instructions:
      - text: List all identities on the user's profile.
      - text: Show the user's identities of type {type}.
        slots:
          type: query.type[]
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/users/{user_id}/identities'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an identity to a user
      effect: write
      questions:
      - How do I add a second email address or phone number to a user's profile?
      - Which identity types can be added, such as google or agent_forwarding?
      instructions:
      - text: Add a new email identity to the user's profile.
      - text: Attach phone number identity {type} to this user.
        slots:
          type: query.type[]
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/users/{user_id}/identities/{user_identity_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Show a user identity
      effect: read
      questions:
      - Can I view one specific identity on a user's profile?
      - What can an end user see when viewing one of their own identities?
      instructions:
      - text: Show one identity from the user's profile by identity ID.
      - text: Fetch the details of a single user identity.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/users/{user_id}/identities/{user_identity_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update or unverify a user identity
      effect: write
      questions:
      - Can I change the value of an existing email identity?
      - Is there a way to mark a verified identity as unverified again?
      instructions:
      - text: Change the value of the user's identity to the new address.
      - text: Unverify that user identity by setting verified to false.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/users/{user_id}/identities/{user_identity_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a user identity
      effect: destructive
      questions:
      - Can I remove an old email or phone identity from a user?
      - Why is a phone number still visible on the profile after deleting its identity?
      instructions:
      - text: Delete that identity from the user's profile.
      - text: Remove the outdated phone identity from this user.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/users/{user_id}/identities/{user_identity_id}/make_primary'].put
  update:
    x-apievangelist-phrasing:
      intent: Make an identity primary
      effect: write
      questions:
      - How do I change which email is a user's primary identity?
      - Can the primary flag be changed through the regular identity update?
      instructions:
      - text: Make that identity the user's primary one.
      - text: Set this email identity as primary for the user.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/users/{user_id}/identities/{user_identity_id}/request_verification'].put
  update:
    x-apievangelist-phrasing:
      intent: Send a verification email for an identity
      effect: write
      questions:
      - Can I send a user an email asking them to confirm they own an address?
      - What does the user receive when verification is requested?
      instructions:
      - text: Send the user a verification email for that email identity.
      - text: Ask the customer to verify ownership of their email address.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/users/{user_id}/identities/{user_identity_id}/verify'].put
  update:
    x-apievangelist-phrasing:
      intent: Mark an identity as verified
      effect: write
      questions:
      - Can an agent mark a user's identity verified without sending an email?
      - Why can't I verify the account owner's email identity this way?
      instructions:
      - text: Mark that user identity as verified directly.
      - text: Set the customer's identity to verified on their behalf.
      method: generated
      generated: '2026-09-26'