# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for act.web.api Companies API
  version: 1.0.0
extends: openapi/act-companies-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: 23
- target: $.paths['/api/contacts/{contactId}/associated-companies'].get
  update:
    x-apievangelist-phrasing:
      intent: List companies linked to a contact
      effect: read
      questions:
      - Which companies is a given contact connected to?
      - Can I filter a contact's linked companies with an OData query?
      instructions:
      - text: Show the companies linked to contact {contactId}.
        slots:
          contactId: path.contactId
      - text: List every company contact {contactId} belongs to.
        slots:
          contactId: path.contactId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/{contactId}/associated-companies'].put
  update:
    x-apievangelist-phrasing:
      intent: Link several companies to a contact at once
      effect: write
      questions:
      - Can I attach a batch of companies to one contact in a single call?
      - How do I bulk-link company ids to a contact?
      instructions:
      - text: Link companies {companies} to contact {contactId} in one go.
        slots:
          companies: requestBody.companies
          contactId: path.contactId
      - text: Bulk-associate the company list {companies} with contact {contactId}.
        slots:
          companies: requestBody.companies
          contactId: path.contactId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/{contactId}/associated-companies'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unlink several companies from a contact
      effect: destructive
      questions:
      - Can I detach a whole list of companies from a contact at once?
      - Is there a bulk way to remove company links from a contact?
      instructions:
      - text: Unlink companies {companies} from contact {contactId} in bulk.
        slots:
          companies: requestBody.companies
          contactId: path.contactId
      - text: Remove the company list {companies} from contact {contactId}.
        slots:
          companies: requestBody.companies
          contactId: path.contactId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/{contactId}/associated-companies/{companyId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Link one company to a contact
      effect: write
      questions:
      - How do I connect a contact to a single company in Act!?
      - Can I tie one existing company to a contact record?
      instructions:
      - text: Link company {companyId} to contact {contactId}.
        slots:
          companyId: path.companyId
          contactId: path.contactId
      - text: Make contact {contactId} part of company {companyId}.
        slots:
          contactId: path.contactId
          companyId: path.companyId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/{contactId}/associated-companies/{companyId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unlink one company from a contact
      effect: destructive
      questions:
      - How can I detach a contact from one company without deleting either?
      - Can I remove a single company link from a contact?
      instructions:
      - text: Unlink company {companyId} from contact {contactId}.
        slots:
          companyId: path.companyId
          contactId: path.contactId
      - text: Take contact {contactId} off company {companyId}.
        slots:
          contactId: path.contactId
          companyId: path.companyId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/opportunities/{opportunityId}/associated-companies'].get
  update:
    x-apievangelist-phrasing:
      intent: List companies linked to an opportunity
      effect: read
      questions:
      - Which companies are involved in a particular deal?
      - Can I query the companies attached to an opportunity with OData?
      instructions:
      - text: Show the companies linked to opportunity {opportunityId}.
        slots:
          opportunityId: path.opportunityId
      - text: List every company on deal {opportunityId}.
        slots:
          opportunityId: path.opportunityId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/opportunities/{opportunityId}/associated-companies'].put
  update:
    x-apievangelist-phrasing:
      intent: Link several companies to an opportunity
      effect: write
      questions:
      - Can I add a batch of companies to one deal in a single request?
      - How do I bulk-attach companies to an opportunity?
      instructions:
      - text: Link companies {companies} to opportunity {opportunityId} in one go.
        slots:
          companies: requestBody.companies
          opportunityId: path.opportunityId
      - text: Bulk-attach the company list {companies} to deal {opportunityId}.
        slots:
          companies: requestBody.companies
          opportunityId: path.opportunityId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/opportunities/{opportunityId}/associated-companies'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unlink several companies from an opportunity
      effect: destructive
      questions:
      - Can I detach a list of companies from a deal at once?
      - Is there a bulk way to remove companies from an opportunity?
      instructions:
      - text: Unlink companies {companies} from opportunity {opportunityId} in bulk.
        slots:
          companies: requestBody.companies
          opportunityId: path.opportunityId
      - text: Remove the company list {companies} from deal {opportunityId}.
        slots:
          companies: requestBody.companies
          opportunityId: path.opportunityId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/opportunities/{opportunityId}/associated-companies/{companyId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Link one company to an opportunity
      effect: write
      questions:
      - How do I attach a single company to a deal?
      - Can I add one more company to an existing opportunity?
      instructions:
      - text: Link company {companyId} to opportunity {opportunityId}.
        slots:
          companyId: path.companyId
          opportunityId: path.opportunityId
      - text: Add company {companyId} as a party on deal {opportunityId}.
        slots:
          companyId: path.companyId
          opportunityId: path.opportunityId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/opportunities/{opportunityId}/associated-companies/{companyId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unlink one company from an opportunity
      effect: destructive
      questions:
      - How do I take a single company off a deal?
      - Does removing a company from an opportunity delete the company?
      instructions:
      - text: Unlink company {companyId} from opportunity {opportunityId}.
        slots:
          companyId: path.companyId
          opportunityId: path.opportunityId
      - text: Drop company {companyId} from deal {opportunityId}.
        slots:
          companyId: path.companyId
          opportunityId: path.opportunityId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/companies/{companyId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a company's details
      effect: read
      questions:
      - How do I look up one company record by its id?
      - What does a company record include, like industry, revenue and addresses?
      instructions:
      - text: Fetch company {companyId}.
        slots:
          companyId: path.companyId
      - text: Show me the phone, website and industry for company {companyId}.
        slots:
          companyId: path.companyId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/companies/{companyId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a company record
      effect: write
      questions:
      - How do I overwrite an entire company record with new values?
      - Can I resend a full company to update its billing and shipping addresses?
      instructions:
      - text: Replace company {companyId} with name {name} and website {website}.
        slots:
          companyId: path.companyId
          name: requestBody.name
          website: requestBody.website
      - text: Do a full update of company {companyId} with billing address {billingAddress}.
        slots:
          companyId: path.companyId
          billingAddress: requestBody.billingAddress
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/companies/{companyId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a company
      effect: destructive
      questions:
      - How do I permanently remove a company from the database?
      - Can a deleted company record be restored?
      instructions:
      - text: Delete company {companyId}.
        slots:
          companyId: path.companyId
      - text: Remove the company record {companyId} for good.
        slots:
          companyId: path.companyId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/companies/{companyId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change a few fields on a company
      effect: write
      questions:
      - Can I update only a company's phone number without resending everything?
      - How do I change just the employee count or revenue on a company?
      instructions:
      - text: Set the phone number of company {companyId} to {phone}.
        slots:
          companyId: path.companyId
          phone: requestBody.phone
      - text: Patch company {companyId} so its employee count is {numberOfEmployees}.
        slots:
          companyId: path.companyId
          numberOfEmployees: requestBody.numberOfEmployees
      - text: Move company {companyId} under parent company {parentID}.
        slots:
          companyId: path.companyId
          parentID: requestBody.parentID
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/companies'].get
  update:
    x-apievangelist-phrasing:
      intent: List or search companies
      effect: read
      questions:
      - What companies are in my CRM database?
      - Can I search all companies with an OData filter, for example by industry?
      instructions:
      - text: List all companies.
      - text: Search every company record for ones in the software industry.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/companies'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a company
      effect: write
      questions:
      - How do I add a new company to the database?
      - Can I set the parent company and addresses when creating a company?
      instructions:
      - text: Create a company named {name} with website {website}.
        slots:
          name: requestBody.name
          website: requestBody.website
      - text: Add company {name} in industry {industry} with phone {phone}.
        slots:
          name: requestBody.name
          industry: requestBody.industry
          phone: requestBody.phone
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/activities/{activityId}/associated-companies'].get
  update:
    x-apievangelist-phrasing:
      intent: List companies linked to an activity
      effect: read
      questions:
      - Which companies are attached to a scheduled activity?
      - Can I see the companies tied to a meeting or call?
      instructions:
      - text: Show the companies linked to activity {activityId}.
        slots:
          activityId: path.activityId
      - text: List the companies on scheduled activity {activityId}.
        slots:
          activityId: path.activityId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/{entityName}/{id}/associated-companies'].get
  update:
    x-apievangelist-phrasing:
      intent: List companies linked to a custom entity record
      effect: read
      questions:
      - Which companies are attached to a row in my custom entity?
      - Can I see the companies linked to a custom entity record?
      instructions:
      - text: List companies linked to {entityName} record {id}.
        slots:
          entityName: path.entityName
          id: path.id
      - text: Show the companies tied to custom entity {entityName} row {id}.
        slots:
          entityName: path.entityName
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/companies/{companyId}/access'].get
  update:
    x-apievangelist-phrasing:
      intent: See who can access a company
      effect: read
      questions:
      - Who is allowed to see a particular company record?
      - Is a company public, private or limited to certain users?
      instructions:
      - text: Show the access level for company {companyId}.
        slots:
          companyId: path.companyId
      - text: List who can view company {companyId}.
        slots:
          companyId: path.companyId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/companies/{companyId}/access'].put
  update:
    x-apievangelist-phrasing:
      intent: Change who can access a company
      effect: write
      questions:
      - How do I restrict a company record to specific users?
      - Can I change a company's access level to limited?
      instructions:
      - text: Limit access to company {companyId} to accessors {accessors}.
        slots:
          companyId: path.companyId
          accessors: requestBody.accessors
      - text: Set the access level of company {companyId} to {type}.
        slots:
          companyId: path.companyId
          type: requestBody.type
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/companies/{companyId}/divisions'].get
  update:
    x-apievangelist-phrasing:
      intent: List a company's divisions
      effect: read
      questions:
      - What divisions sit under a parent company?
      - How do I see a company's subsidiaries in the hierarchy?
      instructions:
      - text: List the divisions of company {companyId}.
        slots:
          companyId: path.companyId
      - text: Show the child divisions under company {companyId}.
        slots:
          companyId: path.companyId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/companies/webinfo'].get
  update:
    x-apievangelist-phrasing:
      intent: List company web info links
      effect: read
      questions:
      - What web info hyperlinks are configured for companies?
      - Can I filter the company web info links with OData?
      instructions:
      - text: List the company web info hyperlinks.
      - text: Show all web info link groups available for companies.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/companies/webinfo/{id}/HyperLink/{linkId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a company web info link
      effect: write
      questions:
      - How do I change the URL of a company web info hyperlink?
      - Can I rename a link inside a web info group?
      instructions:
      - text: Point link {linkId} in web info group {id} to {href}.
        slots:
          linkId: path.linkId
          id: path.id
          href: requestBody.href
      - text: Rename web info link {linkId} in group {id} to {name}.
        slots:
          linkId: path.linkId
          id: path.id
          name: requestBody.name
      method: generated
      generated: '2026-10-01'