# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Avalara Companies API
  version: 1.0.0
extends: openapi/avalara-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: 27
- target: $.paths['/companies'].get
  update:
    x-apievangelist-phrasing:
      intent: List 1099 payer companies
      effect: read
      questions:
      - Which payer companies have I set up for issuing 1099s?
      - Can I see every payer company on my information-reporting account?
      instructions:
      - text: List my 1099 payer companies.
      - text: Show all payer companies set up for information returns.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/companies'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a 1099 payer company
      effect: write
      questions:
      - Can I add a new payer company with its EIN for 1099 filing?
      - What details does a payer company need before I issue 1099s from it?
      instructions:
      - text: Create a payer company named {name} with EIN {ein}.
        slots:
          name: requestBody.name
          ein: requestBody.ein
      - text: Add payer {name} with contact {contactName} at {contactEmail}.
        slots:
          name: requestBody.name
          contactName: requestBody.contactName
          contactEmail: requestBody.contactEmail
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/companies'].get
  update:
    x-apievangelist-phrasing:
      intent: List AvaTax companies in my account
      effect: read
      questions:
      - Which AvaTax companies exist under my account?
      - Can I sort and filter the companies in my AvaTax account?
      instructions:
      - text: List all AvaTax companies in my account.
      - text: List AvaTax companies matching {filter} ordered by {orderBy}.
        slots:
          filter: query.$filter
          orderBy: query.$orderBy
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/companies'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an AvaTax company
      effect: write
      questions:
      - Can I create a new legal entity in AvaTax to calculate tax for?
      - What fields can I set when adding an AvaTax company manually, like base currency?
      instructions:
      - text: Create an AvaTax company {name} with company code {companyCode}.
        slots:
          name: requestBody.name
          companyCode: requestBody.companyCode
      - text: Add AvaTax company {name} with default country {defaultCountry} and currency {baseCurrencyCode}.
        slots:
          name: requestBody.name
          defaultCountry: requestBody.defaultCountry
          baseCurrencyCode: requestBody.baseCurrencyCode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/companies/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve an AvaTax company by ID
      effect: read
      questions:
      - Can I fetch an AvaTax company by its numeric ID along with its settings?
      - What does the AvaTax record for one company contain?
      instructions:
      - text: Retrieve AvaTax company {id}.
        slots:
          id: path.id
      - text: Get AvaTax company {id} including {include}.
        slots:
          id: path.id
          include: query.$include
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/companies/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an AvaTax company
      effect: write
      questions:
      - Can I change the taxpayer ID on an AvaTax company?
      - Is it possible to make a different AvaTax company my default?
      instructions:
      - text: Update AvaTax company {id} with name {name}.
        slots:
          id: path.id
          name: requestBody.name
      - text: Set AvaTax company {id} taxpayer ID to {taxpayerIdNumber}.
        slots:
          id: path.id
          taxpayerIdNumber: requestBody.taxpayerIdNumber
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/companies/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an AvaTax company
      effect: destructive
      questions:
      - Can I delete an AvaTax company I set up for testing?
      - What happens to transactions when an AvaTax company is deleted?
      instructions:
      - text: Delete AvaTax company {id}.
        slots:
          id: path.id
      - text: Remove the AvaTax company with ID {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/companies/initialize'].post
  update:
    x-apievangelist-phrasing:
      intent: Set up a company with recommended defaults
      effect: write
      questions:
      - How do I quickly set up a new company with default nexus and tax settings?
      - Can I create a company and its primary contact in a single step?
      instructions:
      - text: Initialize company {name}, code {companyCode}, tax ID {taxpayerIdNumber}, at {line1}, {city}, {region} {postalCode}, {country}.
        slots:
          name: requestBody.name
          companyCode: requestBody.companyCode
          taxpayerIdNumber: requestBody.taxpayerIdNumber
          line1: requestBody.line1
          city: requestBody.city
          region: requestBody.region
          postalCode: requestBody.postalCode
          country: requestBody.country
      - text: Quick-start company {companyCode} with contact email {email} using recommended defaults.
        slots:
          companyCode: requestBody.companyCode
          email: requestBody.email
      method: generated
      generated: '2026-09-26'
- target: $.paths['/companies/{companyId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a company record by ID
      effect: read
      questions:
      - Can I look up a company record by its company ID to check its tax payer ID?
      - Where do I see the address and contact email stored on a company record?
      instructions:
      - text: Get company record {companyId}.
        slots:
          companyId: path.companyId
      - text: Show the address and phone on company record {companyId}.
        slots:
          companyId: path.companyId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/companies/{companyId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a company record
      effect: write
      questions:
      - Can I change the email or phone number on a company record?
      - Is there a way to mark a company record inactive?
      instructions:
      - text: Update company record {companyId} with name {companyName}.
        slots:
          companyId: path.companyId
          companyName: requestBody.companyName
      - text: Change the email on company record {companyId} to {email}.
        slots:
          companyId: path.companyId
          email: requestBody.email
      method: generated
      generated: '2026-09-26'
- target: $.paths['/companies/{companyId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a company record
      effect: destructive
      questions:
      - Can I remove a company record I no longer need?
      - Is deleting a company record by company ID permanent?
      instructions:
      - text: Delete company record {companyId}.
        slots:
          companyId: path.companyId
      - text: Remove the company record {companyId} from my account.
        slots:
          companyId: path.companyId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/companies/{id}/certify'].get
  update:
    x-apievangelist-phrasing:
      intent: Self-test a company's integration
      effect: read
      questions:
      - Is my integration for a client company ready to hand over to them?
      - Can I check a company's recent transactions to certify the connector I built?
      instructions:
      - text: Run the integration certification check on company {id}.
        slots:
          id: path.id
      - text: Review the last 100 transactions of company {id} for integration problems.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{id}/filingstatus'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a company's Managed Returns filing status
      effect: read
      questions:
      - Is Avalara currently filing tax returns for one of my companies?
      - What filing status has the compliance team set on my company?
      instructions:
      - text: Get the filing status of company {id}.
        slots:
          id: path.id
      - text: Show whether returns are being filed on behalf of company {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{id}/filingstatus'].post
  update:
    x-apievangelist-phrasing:
      intent: Request a filing status change
      effect: write
      questions:
      - How do I ask Avalara to start filing returns for my company?
      - Which filing status changes can I request myself?
      instructions:
      - text: Change the filing status of company {id}.
        slots:
          id: path.id
      - text: Request that Avalara begin filing returns for company {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/parameters'].get
  update:
    x-apievangelist-phrasing:
      intent: List a company's tax-affecting parameters
      effect: read
      questions:
      - Which company-level parameters, like primary address, affect how my company is taxed?
      - Can I see every parameter set on my company?
      instructions:
      - text: List the parameters on company {companyId}.
        slots:
          companyId: path.companyId
      - text: Show all company-level tax properties for {companyId}.
        slots:
          companyId: path.companyId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/parameters'].post
  update:
    x-apievangelist-phrasing:
      intent: Add parameters to a company
      effect: write
      questions:
      - How do I set a company-level parameter that applies by default in tax calculation?
      - Can I add several parameters to a company at once?
      instructions:
      - text: Add parameters to company {companyId}.
        slots:
          companyId: path.companyId
      - text: Create new company-level tax properties on {companyId}.
        slots:
          companyId: path.companyId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{id}/funding/setup'].post
  update:
    x-apievangelist-phrasing:
      intent: Request funding setup for Managed Returns
      effect: write
      questions:
      - What do I need to do before Avalara can pay my tax returns from my bank?
      - Can I send a funding setup request by email or an embedded widget?
      instructions:
      - text: Submit a funding setup request for company {id}.
        slots:
          id: path.id
      - text: Start the bank funding configuration for company {id} so returns can be filed.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/parameters/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one company parameter
      effect: read
      questions:
      - Can I fetch a single company parameter by its ID?
      - What value does one specific company-level parameter hold?
      instructions:
      - text: Get parameter {id} of company {companyId}.
        slots:
          id: path.id
          companyId: path.companyId
      - text: Show the value of company parameter {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/parameters/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update one company parameter
      effect: write
      questions:
      - How do I change the value of an existing company parameter?
      - Can I edit one company parameter without resending the others?
      instructions:
      - text: Update parameter {id} of company {companyId}.
        slots:
          id: path.id
          companyId: path.companyId
      - text: Change the value stored in company parameter {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/parameters/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a company parameter
      effect: destructive
      questions:
      - Can I remove a parameter I no longer want applied to my company?
      - Is there a way to drop one company-level tax property?
      instructions:
      - text: Delete parameter {id} from company {companyId}.
        slots:
          id: path.id
          companyId: path.companyId
      - text: Remove company parameter {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/funding/configuration'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a company's funding configuration
      effect: read
      questions:
      - How is funding configured for my company's Managed Returns payments?
      - Can I check the current funding configuration of one company?
      instructions:
      - text: Get the funding configuration for company {companyId}.
        slots:
          companyId: path.companyId
      - text: Show how company {companyId} is set up to fund its returns.
        slots:
          companyId: path.companyId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/funding/configurations'].get
  update:
    x-apievangelist-phrasing:
      intent: List funding configurations by currency
      effect: read
      questions:
      - Does my company have separate funding configurations for each currency?
      - Which per-currency funding setups exist on one company?
      instructions:
      - text: List the funding configurations per currency for company {companyId}.
        slots:
          companyId: path.companyId
      - text: Show every currency's funding setup on company {companyId}.
        slots:
          companyId: path.companyId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{id}/configuration'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a company's configuration settings
      effect: read
      questions:
      - Which configuration settings are stored on my company?
      - Can I read the custom X- category settings I saved on a company?
      instructions:
      - text: Get the configuration settings for company {id}.
        slots:
          id: path.id
      - text: List every config setting tied to company {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{id}/configuration'].post
  update:
    x-apievangelist-phrasing:
      intent: Set a company's configuration settings
      effect: write
      questions:
      - How do I store my own company-level settings under a custom category?
      - Which category name is reserved and can't be used for my settings?
      instructions:
      - text: Update the configuration settings for company {id}.
        slots:
          id: path.id
      - text: Save a custom X- category setting on company {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{id}/paymentdetails/{periodyear}/{periodmonth}'].get
  update:
    x-apievangelist-phrasing:
      intent: List ACH payment entries for a period
      effect: read
      questions:
      - Which ACH payments did Avalara make for my company in a given month?
      - Can I trace the payment entries for one filing period?
      instructions:
      - text: List ACH entry details for company {id} in {periodmonth}/{periodyear}.
        slots:
          id: path.id
          periodmonth: path.periodmonth
          periodyear: path.periodyear
      - text: Show payment trace records for company {id}, year {periodyear}, month {periodmonth}.
        slots:
          id: path.id
          periodyear: path.periodyear
          periodmonth: path.periodmonth
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{id}/funding'].get
  update:
    x-apievangelist-phrasing:
      intent: List a company's funding setup requests
      effect: read
      questions:
      - What is the status of the funding requests I submitted for my company?
      - Can I see every funding setup or adjustment request a company has made?
      instructions:
      - text: List funding requests for company {id}.
        slots:
          id: path.id
      - text: Show the status of each funding setup request on company {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/mrs'].get
  update:
    x-apievangelist-phrasing:
      intent: List companies with Managed Returns active
      effect: read
      questions:
      - Which of my companies have the Managed Returns service turned on?
      - Can I list only companies with an active MRS subscription?
      instructions:
      - text: List my companies with an active Managed Returns service.
      - text: Show which companies are enrolled in MRS.
      method: generated
      generated: '2026-10-01'