# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Identity.DirectoryManagement Admin.people Admin Settings API
  version: 1.0.0
extends: openapi/azure-ad-admin-peopleadminsettings-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: 27
- target: $.paths['/admin/people'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the organization's people admin settings
      effect: read
      questions:
      - Where can I see all the people settings an admin has configured for our organization?
      - What does the peopleAdminSettings object hold for profile cards, pronouns and insights?
      instructions:
      - text: Get our organization's people admin settings.
      - text: Show the peopleAdminSettings object with its relationships.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/people/itemInsights'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the organization's item insights privacy settings
      effect: read
      questions:
      - Are item insights turned on for our organization right now?
      - Which group, if any, has item insights disabled in our tenant?
      instructions:
      - text: Show the item insights privacy settings for the organization.
      - text: Check whether item insights are enabled across our tenant.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/people/itemInsights'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove the organization's item insights settings
      effect: destructive
      questions:
      - Can I delete the item insights settings object for the whole organization?
      - What happens if I clear out the tenant's configured item insights settings?
      instructions:
      - text: Delete the organization's item insights settings.
      - text: Remove the itemInsights settings only if its ETag is {etag}.
        slots:
          etag: header.If-Match
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/people/itemInsights'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change who can see item insights in the organization
      effect: write
      questions:
      - How do I turn off item insights for the entire organization?
      - Can I disable item insights for just one Microsoft Entra group?
      instructions:
      - text: Set item insights enabled for the organization to {enabled}.
        slots:
          enabled: requestBody.isEnabledInOrganization
      - text: Disable item insights for members of group {group}.
        slots:
          group: requestBody.disabledForGroup
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/people/profileCardProperties'].get
  update:
    x-apievangelist-phrasing:
      intent: List custom profile card properties
      effect: read
      questions:
      - Which extra attributes have we added to people's profile cards?
      - What profile card properties are configured for our organization?
      instructions:
      - text: List all profile card properties configured for the organization.
      - text: Show every directory attribute we surface on profile cards.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/people/profileCardProperties'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a property to the organization's profile card
      effect: write
      questions:
      - How do I show an extra directory attribute on everyone's profile card?
      - Can I give a new profile card field a localized display label?
      instructions:
      - text: Add directory attribute {attribute} to the profile card.
        slots:
          attribute: requestBody.directoryPropertyName
      - text: Add {attribute} to profile cards with the display annotations {annotations}.
        slots:
          attribute: requestBody.directoryPropertyName
          annotations: requestBody.annotations
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/people/profileCardProperties/{profileCardProperty-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one profile card property
      effect: read
      questions:
      - How is a specific attribute configured on our profile cards?
      - Can I look up one profile card property by its directory property name?
      instructions:
      - text: Get profile card property {property}.
        slots:
          property: path.profileCardProperty-id
      - text: Show the labels and visibility set for profile card field {property}.
        slots:
          property: path.profileCardProperty-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/people/profileCardProperties/{profileCardProperty-id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a property from the profile card
      effect: destructive
      questions:
      - How do I take a custom attribute off everyone's profile card?
      - Does removing a profile card property also drop its localized labels?
      instructions:
      - text: Remove profile card property {property}.
        slots:
          property: path.profileCardProperty-id
      - text: Delete {property} from the profile card along with its localized customizations.
        slots:
          property: path.profileCardProperty-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/people/profileCardProperties/{profileCardProperty-id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a profile card property
      effect: write
      questions:
      - Can I hide an existing profile card field without deleting it?
      - How do I change the display label of a profile card attribute we already added?
      instructions:
      - text: Set visibility of profile card property {property} to {visible}.
        slots:
          property: path.profileCardProperty-id
          visible: requestBody.isVisible
      - text: Replace the annotations on existing profile card property {property} with {annotations}.
        slots:
          property: path.profileCardProperty-id
          annotations: requestBody.annotations
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/people/profileCardProperties/$count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count profile card properties
      effect: read
      questions:
      - How many custom properties are on our profile cards?
      - What's the total number of profile card properties defined?
      instructions:
      - text: Count the profile card properties in the organization.
      - text: Tell me how many attributes we've added to the profile card.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/people/profilePropertySettings'].get
  update:
    x-apievangelist-phrasing:
      intent: List profile property settings
      effect: read
      questions:
      - Which user profile property settings are configured in our organization?
      - What source priority is set for each user profile property?
      instructions:
      - text: List all profile property settings.
      - text: Show how each user profile property is configured, including prioritized sources.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/people/profilePropertySettings'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a profile property setting
      effect: write
      questions:
      - How do I define which sources take priority for a user profile property?
      - Can I add a new profile property setting with a display name?
      instructions:
      - text: Create a profile property setting named {name}.
        slots:
          name: requestBody.name
      - text: Create profile property setting {name} with prioritized sources {sources}.
        slots:
          name: requestBody.name
          sources: requestBody.prioritizedSourceUrls
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/people/profilePropertySettings/{profilePropertySetting-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one profile property setting
      effect: read
      questions:
      - How is one specific profile property setting configured?
      - Can I read a single profile property setting by its ID?
      instructions:
      - text: Get profile property setting {setting}.
        slots:
          setting: path.profilePropertySetting-id
      - text: Show the source priority order for profile property setting {setting}.
        slots:
          setting: path.profilePropertySetting-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/people/profilePropertySettings/{profilePropertySetting-id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a profile property setting
      effect: destructive
      questions:
      - How do I remove a profile property setting we no longer need?
      - Can I delete a profile property setting only if it hasn't changed since I read it?
      instructions:
      - text: Delete profile property setting {setting}.
        slots:
          setting: path.profilePropertySetting-id
      - text: Delete profile property setting {setting} if its ETag still matches {etag}.
        slots:
          setting: path.profilePropertySetting-id
          etag: header.If-Match
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/people/profilePropertySettings/{profilePropertySetting-id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a profile property setting
      effect: write
      questions:
      - How do I reorder the prioritized sources on an existing profile property setting?
      - Can I rename a profile property setting's display name?
      instructions:
      - text: Set the prioritized sources of profile property setting {setting} to {sources}.
        slots:
          setting: path.profilePropertySetting-id
          sources: requestBody.prioritizedSourceUrls
      - text: Change the display name of profile property setting {setting} to {displayName}.
        slots:
          setting: path.profilePropertySetting-id
          displayName: requestBody.displayName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/people/profilePropertySettings/$count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count profile property settings
      effect: read
      questions:
      - How many profile property settings exist in our tenant?
      - What's the number of configured profile property settings?
      instructions:
      - text: Count the profile property settings.
      - text: Tell me how many profile property settings the organization has.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/people/profileSources'].get
  update:
    x-apievangelist-phrasing:
      intent: List profile data sources
      effect: read
      questions:
      - Which external and built-in data sources feed our user profiles?
      - What profile sources are connected to our organization?
      instructions:
      - text: List all profile sources for the organization.
      - text: Show every external and Microsoft data source configured for profiles.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/people/profileSources'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a profile data source
      effect: write
      questions:
      - How do I connect a new external data source for user profiles?
      - Can I register a profile source with its own web URL and localized names?
      instructions:
      - text: Create a profile source named {displayName} with source ID {sourceId}.
        slots:
          displayName: requestBody.displayName
          sourceId: requestBody.sourceId
      - text: Add profile source {sourceId} of kind {kind} linking to {webUrl}.
        slots:
          sourceId: requestBody.sourceId
          kind: requestBody.kind
          webUrl: requestBody.webUrl
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/people/profileSources/{profileSource-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a profile source by its object ID
      effect: read
      questions:
      - How is one profile data source set up, looked up by its object ID?
      - Can I read a single profile source's display name and web URL by ID?
      instructions:
      - text: Get profile source {source} by its object ID.
        slots:
          source: path.profileSource-id
      - text: Show the configuration of profile source object {source}.
        slots:
          source: path.profileSource-id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/people/profileSources/{profileSource-id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a profile source by its object ID
      effect: destructive
      questions:
      - How do I disconnect a profile data source using its object ID?
      - Can I remove a profile source by object ID only if its ETag matches?
      instructions:
      - text: Delete profile source object {source}.
        slots:
          source: path.profileSource-id
      - text: Delete profile source object {source} if its ETag is {etag}.
        slots:
          source: path.profileSource-id
          etag: header.If-Match
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/people/profileSources/{profileSource-id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a profile source by its object ID
      effect: write
      questions:
      - How do I rename a profile source when I have its object ID?
      - Can I change the web URL of an existing profile source by object ID?
      instructions:
      - text: Rename profile source object {source} to {displayName}.
        slots:
          source: path.profileSource-id
          displayName: requestBody.displayName
      - text: Set the web URL of profile source object {source} to {webUrl}.
        slots:
          source: path.profileSource-id
          webUrl: requestBody.webUrl
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/people/profileSources(sourceId=\'{sourceId}\')'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a profile source by its source ID
      effect: read
      questions:
      - Can I look up a profile source using its sourceId instead of the object ID?
      - How is the profile source with a given source identifier configured?
      instructions:
      - text: Get the profile source whose sourceId is {sourceId}.
        slots:
          sourceId: path.sourceId
      - text: Show the settings of profile source with source identifier {sourceId}.
        slots:
          sourceId: path.sourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/people/profileSources(sourceId=\'{sourceId}\')'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a profile source by its source ID
      effect: destructive
      questions:
      - How do I remove a profile source when I only know its sourceId?
      - Can I delete a profile source addressed by source identifier rather than object ID?
      instructions:
      - text: Delete the profile source with sourceId {sourceId}.
        slots:
          sourceId: path.sourceId
      - text: Remove profile source by source identifier {sourceId} if its ETag matches {etag}.
        slots:
          sourceId: path.sourceId
          etag: header.If-Match
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/people/profileSources(sourceId=\'{sourceId}\')'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a profile source by its source ID
      effect: write
      questions:
      - How do I update a profile source addressed by its sourceId?
      - Can I change localized names on a profile source using its source identifier?
      instructions:
      - text: Rename the profile source with sourceId {sourceId} to {displayName}.
        slots:
          sourceId: path.sourceId
          displayName: requestBody.displayName
      - text: Set localizations {localizations} on profile source with source identifier {sourceId}.
        slots:
          sourceId: path.sourceId
          localizations: requestBody.localizations
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/people/profileSources/$count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count profile sources
      effect: read
      questions:
      - How many profile data sources are configured?
      - What's the total count of profile sources in our organization?
      instructions:
      - text: Count the profile sources.
      - text: Tell me how many data sources feed user profiles.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/people/pronouns'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the organization's pronouns settings
      effect: read
      questions:
      - Is pronouns display turned on for our organization?
      - Where do I check the tenant-wide pronouns setting?
      instructions:
      - text: Show the organization's pronouns settings.
      - text: Check whether pronouns are enabled in our tenant.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/admin/people/pronouns'].patch
  update:
    x-apievangelist-phrasing:
      intent: Turn pronouns on or off for the organization
      effect: write
      questions:
      - How do I enable pronouns on profiles across our organization?
      - Can I switch off pronouns support for the whole tenant?
      instructions:
      - text: Set pronouns enabled for the organization to {enabled}.
        slots:
          enabled: requestBody.isEnabledInOrganization
      - text: Turn on pronouns support organization-wide.
      method: generated
      generated: '2026-10-01'