API Evangelist conversational phrasing for Zendesk Organizations 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 Organizations API
  version: 1.0.0
extends: openapi/zendesk-organizations-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: 24
- target: $.paths['/api/v2/organizations/autocomplete'].get
  update:
    x-apievangelist-phrasing:
      intent: Autocomplete organization names by prefix
      effect: read
      questions:
      - Can I get organizations whose names start with a few letters I typed, using the v2 autocomplete?
      - What does the v2 organization autocomplete return for a partial name?
      instructions:
      - text: Suggest organizations whose names begin with the prefix I type, using the v2 autocomplete endpoint.
      - text: Run the api/v2 organization name autocomplete for a type-ahead box.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/organization_merges/{organization_merge_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the status of an organization merge
      effect: read
      questions:
      - Did the organization merge I started finish, and which org won?
      - Where can I see the status and outcome of one specific organization merge?
      instructions:
      - text: Show the status of the organization merge I kicked off earlier.
      - text: Get the winning and losing organization ids for that merge job.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/organizations'].get
  update:
    x-apievangelist-phrasing:
      intent: List all organizations with cursor pagination
      effect: read
      questions:
      - How do I page through every organization in my Zendesk account with cursor pagination?
      - Which organizations can an agent with a custom role see in the v2 list?
      instructions:
      - text: List every organization in the account using the api/v2 organizations list with cursor pagination.
      - text: Page through all organizations 100 at a time from the v2 endpoint.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/organizations'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an organization
      effect: write
      questions:
      - Does each new organization need a unique name when created through api/v2?
      - What happens if two identical organization create calls race each other?
      instructions:
      - text: Create a new organization with a unique name through the api/v2 organizations endpoint.
      - text: Add one organization for our new enterprise customer via the v2 create call.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/organizations/{organization_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one organization's details
      effect: read
      questions:
      - How can I look up a single organization's details by its id in the v2 API?
      - What fields come back when I fetch one organization from api/v2?
      instructions:
      - text: Show organization {organization_id} from the api/v2 organizations endpoint.
        slots:
          organization_id: path.organization_id
      - text: Fetch the v2 record for org {organization_id} so I can see its domains and tags.
        slots:
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/organizations/{organization_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an organization
      effect: write
      questions:
      - Will updating an organization's domain_names in v2 overwrite the ones already there?
      - Can an agent without extra permissions change anything besides notes on an organization?
      instructions:
      - text: Update the notes on organization {organization_id} using the api/v2 PUT.
        slots:
          organization_id: path.organization_id
      - text: Replace the domain names on org {organization_id} via the v2 update endpoint.
        slots:
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/organizations/{organization_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an organization
      effect: destructive
      questions:
      - Who is allowed to delete an organization through the v2 API?
      - Can I remove a single organization by id with an api/v2 DELETE?
      instructions:
      - text: Delete organization {organization_id} through the api/v2 organizations endpoint.
        slots:
          organization_id: path.organization_id
      - text: Remove org {organization_id} from Zendesk using the v2 delete call.
        slots:
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/organizations/{organization_id}/merge'].post
  update:
    x-apievangelist-phrasing:
      intent: Merge one organization into another
      effect: destructive
      questions:
      - How do I merge two duplicate organizations and move their users and tickets over?
      - What happens to the losing organization after a merge?
      instructions:
      - text: Merge organization {organization_id} into the winning org, moving its users, tickets and domains.
        slots:
          organization_id: path.organization_id
      - text: Fold duplicate org {organization_id} into our main organization and delete the loser.
        slots:
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/organizations/{organization_id}/merges'].get
  update:
    x-apievangelist-phrasing:
      intent: List merge history for an organization
      effect: read
      questions:
      - Which merges has an organization been part of, including ones still running?
      - Can I track the history of merge actions on one organization?
      instructions:
      - text: List all merge operations associated with organization {organization_id}.
        slots:
          organization_id: path.organization_id
      - text: Show the ongoing and completed merges for org {organization_id}.
        slots:
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/organizations/{organization_id}/related'].get
  update:
    x-apievangelist-phrasing:
      intent: Get related counts for an organization
      effect: read
      questions:
      - How many tickets and users are related to an organization?
      - Is there a quick way to see an organization's related information as an agent?
      instructions:
      - text: Show the related information for organization {organization_id}.
        slots:
          organization_id: path.organization_id
      - text: Get ticket and user counts related to org {organization_id}.
        slots:
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/organizations/count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count organizations in the account
      effect: read
      questions:
      - About how many organizations do we have in Zendesk?
      - How fresh is the organization count once it passes 100,000?
      instructions:
      - text: Count the organizations in our account.
      - text: Tell me the approximate organization total and when it was last refreshed.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/organizations/create_many'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk create up to 100 organizations
      effect: write
      questions:
      - Can I create up to 100 organizations in a single background job?
      - How do I track a bulk organization creation job once it's queued?
      instructions:
      - text: Bulk create this batch of up to 100 organizations as a background job.
      - text: Queue a job that creates all the organizations in my spreadsheet at once.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/organizations/create_or_update'].post
  update:
    x-apievangelist-phrasing:
      intent: Create or update an organization (upsert)
      effect: write
      questions:
      - Is there a way to upsert an organization without checking if it exists first?
      - Do I need an id or external id to update an org through create-or-update?
      instructions:
      - text: Upsert this organization by external id, creating it if it doesn't exist yet.
      - text: Create the organization or update it if one with that id already exists.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/organizations/destroy_many'].delete
  update:
    x-apievangelist-phrasing:
      intent: Bulk delete up to 100 organizations
      effect: destructive
      questions:
      - Can I delete many organizations at once by their ids or external ids?
      - What's the limit on how many organizations one bulk delete can remove?
      instructions:
      - text: Bulk delete these organizations by id in one background job.
      - text: Destroy up to 100 organizations listed by external id.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/organizations/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search organizations by name or external id
      effect: read
      questions:
      - How do I find an organization by its external_id using the v2 search?
      - Can I search organizations by name and external id at the same time in api/v2?
      instructions:
      - text: Search api/v2 organizations for the one matching our CRM account's external id.
      - text: Look up an organization by exact name with the v2 organization search.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/organizations/show_many'].get
  update:
    x-apievangelist-phrasing:
      intent: Get several organizations by id at once
      effect: read
      questions:
      - Can I fetch up to 100 specific organizations in one call by id?
      - Is there a batch lookup for organizations using external ids?
      instructions:
      - text: Fetch these specific organizations in one request by their ids.
      - text: Show many organizations at once using a comma-separated list of external ids.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/organizations/update_many'].put
  update:
    x-apievangelist-phrasing:
      intent: Bulk update up to 100 organizations
      effect: write
      questions:
      - How do I apply the same change to many organizations in one request?
      - Can I batch update up to 100 organizations with different changes for each?
      instructions:
      - text: Bulk update these organizations to add the same tag to all of them.
      - text: Batch update up to 100 organizations, each with its own changes.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations'].get
  update:
    x-apievangelist-phrasing:
      intent: List organizations with page and per_page
      effect: read
      questions:
      - Can I list organizations with simple page and per_page parameters on the /organizations endpoint?
      - How many organizations come back per page if I set per_page on the shorter /organizations path?
      instructions:
      - text: List organizations from the /organizations endpoint, page {page}.
        slots:
          page: query.page
      - text: Get {per_page} organizations per page from the /organizations list.
        slots:
          per_page: query.per_page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an organization with domains and tags
      effect: write
      questions:
      - Can I set domains, tags, notes and custom fields when creating an org via the /organizations endpoint?
      - What's required to create an organization through the plain /organizations POST?
      instructions:
      - text: Create organization {organization} through the /organizations endpoint.
        slots:
          organization: requestBody.organization
      - text: POST to /organizations to add {organization} with its domains and tags.
        slots:
          organization: requestBody.organization
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{organization_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Show an organization from the /organizations path
      effect: read
      questions:
      - How do I get one organization's details from the /organizations path by id?
      - Which details does the non-v2 show organization call return?
      instructions:
      - text: Get organization {organization_id} from the /organizations path.
        slots:
          organization_id: path.organization_id
      - text: Show the details of org {organization_id} using the non-v2 endpoint.
        slots:
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{organization_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an organization's name, domains or fields
      effect: write
      questions:
      - Can I change an organization's name, notes and custom fields via the /organizations PUT?
      - Which organization properties are editable through the non-v2 update?
      instructions:
      - text: Update organization {organization_id} with {organization} via the /organizations path.
        slots:
          organization_id: path.organization_id
          organization: requestBody.organization
      - text: Rename org {organization_id} using the non-v2 update endpoint.
        slots:
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/{organization_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Permanently delete an organization
      effect: destructive
      questions:
      - If I permanently delete an organization, what happens to its users?
      - Does deleting an org through the /organizations path remove members' organization membership?
      instructions:
      - text: Permanently delete organization {organization_id} using the /organizations path.
        slots:
          organization_id: path.organization_id
      - text: Remove org {organization_id} via the non-v2 delete, keeping its users.
        slots:
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Find an organization by external id
      effect: read
      questions:
      - Can I pass an external_id query to the /organizations/search path?
      - What does the non-v2 organization search accept?
      instructions:
      - text: Search /organizations for the org with external id {external_id}.
        slots:
          external_id: query.external_id
      - text: Find the organization linked to external record {external_id} using the non-v2 search.
        slots:
          external_id: query.external_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/organizations/autocomplete'].get
  update:
    x-apievangelist-phrasing:
      intent: Type-ahead organization lookup by name
      effect: read
      questions:
      - How do I build a type-ahead that suggests organizations from the /organizations/autocomplete path?
      - Which organizations match a name prefix on the non-v2 autocomplete?
      instructions:
      - text: Autocomplete organizations starting with {name} using the /organizations path.
        slots:
          name: query.name
      - text: Suggest orgs whose names begin with {name} for my type-ahead field.
        slots:
          name: query.name
      method: generated
      generated: '2026-09-26'