# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for VirtoCommerce.Customer Companies and Contacts API
  version: 1.0.0
extends: openapi/virto-commerce-companies-and-contacts-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: 45
- target: $.paths['/api/members/organizations'].get
  update:
    x-apievangelist-phrasing:
      intent: List every organization
      effect: read
      questions:
      - Is there a way to pull the full list of organizations without any search filter?
      - What call returns all organizations registered in Virto Commerce at once?
      instructions:
      - text: List all organizations in the customer module.
      - text: Give me the complete unfiltered organization list.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/members/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search members of any type
      effect: read
      questions:
      - How do I search across contacts, organizations, employees and vendors in one query?
      - Can I find members by keyword and restrict the results to a single member type?
      - Can a member search include nested members of an organization with deep search?
      instructions:
      - text: Search all members for {keyword}.
        slots:
          keyword: requestBody.keyword
      - text: Find members of type {memberType} matching {keyword}.
        slots:
          memberType: requestBody.memberType
          keyword: requestBody.keyword
      - text: Search members under member {memberId} with deep search turned on.
        slots:
          memberId: requestBody.memberId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/members/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a member by ID
      effect: read
      questions:
      - What does a single member record look like when I fetch it by its ID?
      - Can I choose which parts of a member record come back when looking one up by ID?
      instructions:
      - text: Get member {id}.
        slots:
          id: path.id
      - text: Fetch member {id} as member type {memberType}.
        slots:
          id: path.id
          memberType: query.memberType
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/members/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Partially update a member
      effect: write
      questions:
      - Can I change just one field on a member without resending the whole record?
      - How do I apply a JSON patch to a generic member?
      instructions:
      - text: Patch member {id} with only the fields I changed.
        slots:
          id: path.id
      - text: Apply a partial update to member {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/members/accounts/{userId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the member linked to a user account
      effect: read
      questions:
      - Which member record belongs to a given login user account?
      - How do I go from a user account ID to its customer member?
      instructions:
      - text: Get the member for user account {userId}.
        slots:
          userId: path.userId
      - text: Look up the member of type {memberType} tied to user {userId}.
        slots:
          userId: path.userId
          memberType: query.memberType
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/members'].get
  update:
    x-apievangelist-phrasing:
      intent: Get several members by their IDs
      effect: read
      questions:
      - Can I load a batch of members in one request if I already know their IDs?
      - What endpoint fetches multiple members of mixed types by ID list?
      instructions:
      - text: Get the members with IDs {ids}.
        slots:
          ids: query.ids
      - text: Load members {ids} limited to types {memberTypes}.
        slots:
          ids: query.ids
          memberTypes: query.memberTypes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/members'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a member record
      effect: write
      questions:
      - How do I save changes to a member's addresses, phones and emails with a full update?
      - Can I change a member's status by replacing its whole record?
      instructions:
      - text: Update member {name} with the full record I provide.
        slots:
          name: requestBody.name
      - text: Set the status of member {name} to {status}.
        slots:
          name: requestBody.name
          status: requestBody.status
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/members'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a member of any type
      effect: write
      questions:
      - Can I create a new member of any type through one generic endpoint?
      - What fields do I need to add a single new member with its contact details?
      instructions:
      - text: Create a new member named {name} of type {memberType}.
        slots:
          name: requestBody.name
          memberType: requestBody.memberType
      - text: Add member {name} with external ID {outerId}.
        slots:
          name: requestBody.name
          outerId: requestBody.outerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/members'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete members by ID
      effect: destructive
      questions:
      - How do I remove several members at once when I know their IDs?
      - Is deleting members by ID permanent?
      instructions:
      - text: Delete members {ids}.
        slots:
          ids: query.ids
      - text: Remove the member records with IDs {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/members/bulk'].put
  update:
    x-apievangelist-phrasing:
      intent: Update many members in one call
      effect: write
      questions:
      - Can I push updates to a whole batch of members in a single request?
      - What endpoint saves changes to many generic members together?
      instructions:
      - text: Bulk update this list of members.
      - text: Save changes to all these member records in one batch.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/members/bulk'].post
  update:
    x-apievangelist-phrasing:
      intent: Create many members in one call
      effect: write
      questions:
      - Is there a way to import a batch of new members of mixed types at once?
      - Can I create many generic members in one request instead of one by one?
      instructions:
      - text: Bulk create these new members.
      - text: Create all of the members in this list in one batch.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/members/delete'].post
  update:
    x-apievangelist-phrasing:
      intent: Delete all members matching search criteria
      effect: destructive
      questions:
      - Can I delete every member that matches a keyword instead of listing IDs?
      - How do I wipe out all members of one type in a single call?
      instructions:
      - text: Delete all members matching {keyword}.
        slots:
          keyword: requestBody.keyword
      - text: Bulk delete every member of type {memberType}.
        slots:
          memberType: requestBody.memberType
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/members/customers/invite'].post
  update:
    x-apievangelist-phrasing:
      intent: Invite customers by email
      effect: write
      questions:
      - How do I send storefront invitations to a list of customer emails?
      - Can I invite people to join a specific organization with preset roles?
      - Can I add a personal message to a customer invitation?
      instructions:
      - text: Invite {emails} to store {storeId}.
        slots:
          emails: requestBody.emails
          storeId: requestBody.storeId
      - text: Invite {emails} to organization {organizationId} with roles {roleIds}.
        slots:
          emails: requestBody.emails
          organizationId: requestBody.organizationId
          roleIds: requestBody.roleIds
      - text: Send an invitation to {emails} with the message {message}.
        slots:
          emails: requestBody.emails
          message: requestBody.message
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/members/customers/invite/roles'].get
  update:
    x-apievangelist-phrasing:
      intent: List roles available for invitations
      effect: read
      questions:
      - Which roles can I assign to a customer when inviting them?
      - What role options are offered on the invite form?
      instructions:
      - text: List the roles I can grant in a customer invitation.
      - text: Show the available invite roles.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/contacts'].get
  update:
    x-apievangelist-phrasing:
      intent: Get several contacts by their IDs
      effect: read
      questions:
      - Can I fetch a batch of contacts when I have their IDs?
      - What endpoint returns multiple contact people at once by ID?
      instructions:
      - text: Get contacts {ids}.
        slots:
          ids: query.ids
      - text: Load the contact records for IDs {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/contacts'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a contact
      effect: write
      questions:
      - How do I change a contact person's name or birth date?
      - Can I change which organization is a contact's default?
      instructions:
      - text: Update contact {fullName} with a new last name {lastName}.
        slots:
          fullName: requestBody.fullName
          lastName: requestBody.lastName
      - text: Set the default organization of contact {fullName} to {defaultOrganizationId}.
        slots:
          fullName: requestBody.fullName
          defaultOrganizationId: requestBody.defaultOrganizationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/contacts'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a contact
      effect: write
      questions:
      - How do I add a new customer contact person?
      - Can a new contact be linked to organizations when it is created?
      instructions:
      - text: Create a contact {firstName} {lastName}.
        slots:
          firstName: requestBody.firstName
          lastName: requestBody.lastName
      - text: Add a new contact {fullName} belonging to organizations {organizations}.
        slots:
          fullName: requestBody.fullName
          organizations: requestBody.organizations
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/contacts'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete contacts
      effect: destructive
      questions:
      - How do I remove contact people I no longer need?
      - Can I delete several contacts in one request?
      instructions:
      - text: Delete contacts {ids}.
        slots:
          ids: query.ids
      - text: Remove the contact records {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/contacts/bulk'].put
  update:
    x-apievangelist-phrasing:
      intent: Update many contacts at once
      effect: write
      questions:
      - Can I save edits to a whole list of contacts in one call?
      - What endpoint bulk updates contact people?
      instructions:
      - text: Bulk update these contacts.
      - text: Save changes to all of these contact people in one batch.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/contacts/bulk'].post
  update:
    x-apievangelist-phrasing:
      intent: Create many contacts at once
      effect: write
      questions:
      - Is there a way to import a batch of new contacts in one request?
      - Can I create dozens of contact people together?
      instructions:
      - text: Bulk create these new contacts.
      - text: Add every contact in this list in one batch.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/contacts/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a contact by ID
      effect: read
      questions:
      - What details come back for a single contact person?
      - Where do I read one contact's record by its ID?
      instructions:
      - text: Get contact {id}.
        slots:
          id: path.id
      - text: Show me the details of contact {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/contacts/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Partially update a contact
      effect: write
      questions:
      - Can I change one field of a contact without sending the full contact?
      - How do I patch a contact person record?
      instructions:
      - text: Patch contact {id} with only the changed fields.
        slots:
          id: path.id
      - text: Apply a partial update to contact {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/contacts/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search contacts
      effect: read
      questions:
      - How can I find contact people by name or keyword?
      - Can I search only the contacts that belong to one organization?
      instructions:
      - text: Search contacts for {keyword}.
        slots:
          keyword: requestBody.keyword
      - text: Find contacts in organization {memberId} matching {keyword}.
        slots:
          memberId: requestBody.memberId
          keyword: requestBody.keyword
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/organizations'].get
  update:
    x-apievangelist-phrasing:
      intent: Get several organizations by their IDs
      effect: read
      questions:
      - Can I fetch a specific set of organizations by ID in one request?
      - What endpoint returns multiple company accounts when I know their IDs?
      instructions:
      - text: Get organizations {ids}.
        slots:
          ids: query.ids
      - text: Load the organization records for IDs {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/organizations'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an organization
      effect: write
      questions:
      - How do I change a company account's description or business category?
      - Can I move an organization under a different parent organization?
      instructions:
      - text: Update organization {name} with business category {businessCategory}.
        slots:
          name: requestBody.name
          businessCategory: requestBody.businessCategory
      - text: Set the parent of organization {name} to {parentId}.
        slots:
          name: requestBody.name
          parentId: requestBody.parentId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/organizations'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an organization
      effect: write
      questions:
      - How do I register a new B2B company account?
      - Can I create an organization as a child of another one?
      instructions:
      - text: Create an organization named {name}.
        slots:
          name: requestBody.name
      - text: Create organization {name} under parent organization {parentId} owned by {ownerId}.
        slots:
          name: requestBody.name
          parentId: requestBody.parentId
          ownerId: requestBody.ownerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/organizations'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete organizations
      effect: destructive
      questions:
      - How do I delete company accounts I no longer serve?
      - Can several organizations be deleted together?
      instructions:
      - text: Delete organizations {ids}.
        slots:
          ids: query.ids
      - text: Remove the organization records {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/organizations/bulk'].put
  update:
    x-apievangelist-phrasing:
      intent: Update many organizations at once
      effect: write
      questions:
      - Can I save changes to a batch of organizations in one request?
      - What endpoint bulk updates company accounts?
      instructions:
      - text: Bulk update these organizations.
      - text: Save edits to all of these organizations in one batch.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/organizations/bulk'].post
  update:
    x-apievangelist-phrasing:
      intent: Create many organizations at once
      effect: write
      questions:
      - Is there a way to import a list of new company accounts in one go?
      - Can I create many organizations with a single call?
      instructions:
      - text: Bulk create these organizations.
      - text: Add every organization in this list in one batch.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/organizations/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an organization by ID
      effect: read
      questions:
      - What does one organization's record contain?
      - Where can I read a single company account by its ID?
      instructions:
      - text: Get organization {id}.
        slots:
          id: path.id
      - text: Show me the details of organization {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/organizations/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Partially update an organization
      effect: write
      questions:
      - Can I change a single field on an organization without resending it all?
      - How do I patch a company account?
      instructions:
      - text: Patch organization {id} with only the changed fields.
        slots:
          id: path.id
      - text: Apply a partial update to organization {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/organizations/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search organizations
      effect: read
      questions:
      - How can I find organizations by name or keyword?
      - Can I search for the child organizations under a parent?
      instructions:
      - text: Search organizations for {keyword}.
        slots:
          keyword: requestBody.keyword
      - text: Find organizations under {memberId} matching {keyword}.
        slots:
          memberId: requestBody.memberId
          keyword: requestBody.keyword
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/vendors/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a vendor by ID
      effect: read
      questions:
      - What information is stored for a single vendor?
      - Where do I read one seller or vendor record by ID?
      instructions:
      - text: Get vendor {id}.
        slots:
          id: path.id
      - text: Show me the details of vendor {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/vendors'].get
  update:
    x-apievangelist-phrasing:
      intent: Get several vendors by their IDs
      effect: read
      questions:
      - Can I load a batch of vendors when I have their IDs?
      - What endpoint returns multiple vendors at once?
      instructions:
      - text: Get vendors {ids}.
        slots:
          ids: query.ids
      - text: Load the vendor records for IDs {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/vendors/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search vendors
      effect: read
      questions:
      - How can I find vendors by name or keyword?
      - Is there a paged search over all vendors?
      instructions:
      - text: Search vendors for {keyword}.
        slots:
          keyword: requestBody.keyword
      - text: List vendors sorted by {sort}.
        slots:
          sort: requestBody.sort
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/addresses'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a member's addresses
      effect: write
      questions:
      - How do I update the address book of a customer or organization?
      - Can I overwrite all addresses of one member in a single call?
      instructions:
      - text: Update the addresses of member {memberId}.
        slots:
          memberId: query.memberId
      - text: Replace member {memberId}'s addresses with this list.
        slots:
          memberId: query.memberId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/employees'].get
  update:
    x-apievangelist-phrasing:
      intent: Get several employees by their IDs
      effect: read
      questions:
      - Can I fetch staff employee records by ID in one call?
      - What endpoint returns multiple employees at once?
      instructions:
      - text: Get employees {ids}.
        slots:
          ids: query.ids
      - text: Load the employee records for IDs {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/employees'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an employee
      effect: write
      questions:
      - How do I add a new staff employee record?
      - Can I set an employee's type and active status when creating them?
      instructions:
      - text: Create employee {firstName} {lastName}.
        slots:
          firstName: requestBody.firstName
          lastName: requestBody.lastName
      - text: Add employee {fullName} of type {employeeType}.
        slots:
          fullName: requestBody.fullName
          employeeType: requestBody.employeeType
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/employees/bulk'].post
  update:
    x-apievangelist-phrasing:
      intent: Create many employees at once
      effect: write
      questions:
      - Is there a way to import a batch of staff employees in one request?
      - Can I create several employee records together?
      instructions:
      - text: Bulk create these employees.
      - text: Add every employee in this list in one batch.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/members/{id}/organizations'].get
  update:
    x-apievangelist-phrasing:
      intent: List the organizations a member belongs to
      effect: read
      questions:
      - Which organizations is a given contact a member of?
      - How do I see every company a member is associated with?
      instructions:
      - text: List the organizations member {id} belongs to.
        slots:
          id: path.id
      - text: Show all organizations associated with member {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/customer-preferences/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search customer preferences
      effect: read
      questions:
      - How can I find the saved preferences for a particular user?
      - Can I search customer preferences by preference name?
      instructions:
      - text: Search preferences saved by user {userId}.
        slots:
          userId: requestBody.userId
      - text: Find customer preferences named {name}.
        slots:
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/customer-preferences'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a customer preference
      effect: write
      questions:
      - How do I change the value of a stored customer preference?
      - Can I overwrite a user's existing preference setting?
      instructions:
      - text: Update preference {id} to value {value}.
        slots:
          id: requestBody.id
          value: requestBody.value
      - text: Change user {userId}'s {name} preference to {value}.
        slots:
          userId: requestBody.userId
          name: requestBody.name
          value: requestBody.value
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/customer-preferences'].post
  update:
    x-apievangelist-phrasing:
      intent: Save a new customer preference
      effect: write
      questions:
      - Can I store a new named preference for a customer?
      - What is needed to save a user preference for the first time?
      instructions:
      - text: Create a preference {name} with value {value} for user {userId}.
        slots:
          name: requestBody.name
          value: requestBody.value
          userId: requestBody.userId
      - text: Save a new preference {name} for user {userId}.
        slots:
          name: requestBody.name
          userId: requestBody.userId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/customer-preferences'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete customer preferences
      effect: destructive
      questions:
      - How do I remove saved customer preferences?
      - Can I delete several preferences by ID?
      instructions:
      - text: Delete customer preferences {ids}.
        slots:
          ids: query.ids
      - text: Remove the saved preference records {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/customer-preferences/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a customer preference by ID
      effect: read
      questions:
      - What value does a specific stored preference hold?
      - Where do I read a single customer preference by ID?
      instructions:
      - text: Get customer preference {id}.
        slots:
          id: path.id
      - text: Show the preference record {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'