# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Avalara Customers API
  version: 1.0.0
extends: openapi/avalara-customers-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: 18
- target: $.paths['/api/v2/companies/{companyId}/customers'].get
  update:
    x-apievangelist-phrasing:
      intent: List an AvaTax company's customers
      effect: read
      questions:
      - Which customers are recorded under my AvaTax company?
      - Can I filter an AvaTax company's customer list?
      instructions:
      - text: List customers for AvaTax company {companyId}.
        slots:
          companyId: path.companyId
      - text: Show customers of company {companyId} matching {filter}.
        slots:
          companyId: path.companyId
          filter: query.$filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/companies/{companyId}/customers'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a customer under an AvaTax company
      effect: write
      questions:
      - Can I add a customer record directly under a specific AvaTax company?
      - Where do I create customers scoped to one company ID for exemption tracking?
      instructions:
      - text: Create a new customer under AvaTax company {companyId}.
        slots:
          companyId: path.companyId
      - text: Add a customer record to company {companyId}.
        slots:
          companyId: path.companyId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/customers'].get
  update:
    x-apievangelist-phrasing:
      intent: List all customers
      effect: read
      questions:
      - What customers do I have in my exemption certificate account?
      - Can I page through my full customer list?
      instructions:
      - text: List my customers.
      - text: Show customers page {page} with {pageSize} per page.
        slots:
          page: query.page
          pageSize: query.pageSize
      method: generated
      generated: '2026-09-26'
- target: $.paths['/customers'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a customer
      effect: write
      questions:
      - How do I add a new customer with a customer code and address?
      - Can I store a customer's email and phone when creating them?
      instructions:
      - text: Create customer {name} with code {customerCode}.
        slots:
          name: requestBody.name
          customerCode: requestBody.customerCode
      - text: Add customer {name} at {line1}, {city}, {region} {postalCode}.
        slots:
          name: requestBody.name
          line1: requestBody.line1
          city: requestBody.city
          region: requestBody.region
          postalCode: requestBody.postalCode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/customers/{customerId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a customer by ID
      effect: read
      questions:
      - Can I pull up a single customer's details by ID?
      - What address is on file for a given customer?
      instructions:
      - text: Get customer {customerId}.
        slots:
          customerId: path.customerId
      - text: Show contact details for customer {customerId}.
        slots:
          customerId: path.customerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/customers/{customerId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a customer
      effect: write
      questions:
      - Can I change a customer's address after they move?
      - Is it possible to update a customer's email address?
      instructions:
      - text: Update customer {customerId} with email {emailAddress}.
        slots:
          customerId: path.customerId
          emailAddress: requestBody.emailAddress
      - text: Change customer {customerId} address to {line1}, {city}, {region}.
        slots:
          customerId: path.customerId
          line1: requestBody.line1
          city: requestBody.city
          region: requestBody.region
      method: generated
      generated: '2026-09-26'
- target: $.paths['/customers/{customerId}/certificates'].get
  update:
    x-apievangelist-phrasing:
      intent: List a customer's certificates
      effect: read
      questions:
      - Which exemption certificates does a specific customer have on file?
      - Can I check whether one customer has any certificates at all?
      instructions:
      - text: List certificates for customer {customerId}.
        slots:
          customerId: path.customerId
      - text: Show every exemption certificate customer {customerId} has submitted.
        slots:
          customerId: path.customerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/companies/{companyId}/customers/{customerCode}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a company customer by customer code
      effect: read
      questions:
      - Can I look up a customer in an AvaTax company by their customer code?
      - What exemption details are stored for the customer code I pass on transactions?
      instructions:
      - text: Get customer {customerCode} in company {companyId}.
        slots:
          customerCode: path.customerCode
          companyId: path.companyId
      - text: Show the AvaTax customer record for code {customerCode}.
        slots:
          customerCode: path.customerCode
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/customers/{customerCode}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a company customer by customer code
      effect: write
      questions:
      - How do I update a customer record I reference by customer code on transactions?
      - Does replacing an AvaTax company customer clear the fields I leave out?
      instructions:
      - text: Update customer {customerCode} in company {companyId}.
        slots:
          customerCode: path.customerCode
          companyId: path.companyId
      - text: Replace the record for customer code {customerCode} with new details.
        slots:
          customerCode: path.customerCode
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/customers/{customerCode}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a company customer by customer code
      effect: destructive
      questions:
      - How do I remove a customer from my AvaTax company?
      - Can I delete a customer record by its customer code?
      instructions:
      - text: Delete customer {customerCode} from company {companyId}.
        slots:
          customerCode: path.customerCode
          companyId: path.companyId
      - text: Remove the customer with code {customerCode}.
        slots:
          customerCode: path.customerCode
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/customers/{customerCode}/attributes/link'].put
  update:
    x-apievangelist-phrasing:
      intent: Link attributes to a customer
      effect: write
      questions:
      - How do I attach behavior-controlling attributes to a customer?
      - Can I link several customer attributes in one request?
      instructions:
      - text: Link attributes to customer {customerCode} in company {companyId}.
        slots:
          customerCode: path.customerCode
          companyId: path.companyId
      - text: Add attributes to customer {customerCode}.
        slots:
          customerCode: path.customerCode
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/customers/{customerCode}/certificates/link'].post
  update:
    x-apievangelist-phrasing:
      intent: Link exemption certificates to a customer
      effect: write
      questions:
      - How do I associate an existing exemption certificate with a customer?
      - Can I link more than one certificate to a customer at a time?
      instructions:
      - text: Link certificates to customer {customerCode} in company {companyId}.
        slots:
          customerCode: path.customerCode
          companyId: path.companyId
      - text: Attach exemption certificates to customer {customerCode}.
        slots:
          customerCode: path.customerCode
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/customers/billto/{code}/shipto/link'].post
  update:
    x-apievangelist-phrasing:
      intent: Link ship-to customers to a bill-to customer
      effect: write
      questions:
      - How do I group ship-to customer records under one billing customer?
      - Can certificates on a bill-to customer cover its shipping addresses?
      instructions:
      - text: Link ship-to customers to bill-to customer {code} in company {companyId}.
        slots:
          code: path.code
          companyId: path.companyId
      - text: Group shipping customer records under bill-to customer {code}.
        slots:
          code: path.code
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/customers/{customerCode}/attributes'].get
  update:
    x-apievangelist-phrasing:
      intent: List the attributes linked to a customer
      effect: read
      questions:
      - Which attributes are currently linked to a customer?
      - Can I check what attributes control a customer's behavior?
      instructions:
      - text: List attributes for customer {customerCode} in company {companyId}.
        slots:
          customerCode: path.customerCode
          companyId: path.companyId
      - text: Show the attributes linked to customer {customerCode}.
        slots:
          customerCode: path.customerCode
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/customers/{customerCode}/certificates'].get
  update:
    x-apievangelist-phrasing:
      intent: List certificates linked to a company customer
      effect: read
      questions:
      - Which certificates are linked to a customer code in my AvaTax company?
      - Can I list a company customer's certificates by customer code?
      instructions:
      - text: List certificates linked to customer code {customerCode} in company {companyId}.
        slots:
          customerCode: path.customerCode
          companyId: path.companyId
      - text: Show linked certificates for AvaTax customer code {customerCode}.
        slots:
          customerCode: path.customerCode
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/customers/{customerCode}/certificates/{country}/{region}'].get
  update:
    x-apievangelist-phrasing:
      intent: List a customer's valid certificates for a region
      effect: read
      questions:
      - Does this customer already have a valid certificate for a given state?
      - Can I check which certificates cover a customer in one country and region?
      instructions:
      - text: List valid certificates for customer {customerCode} in {country} {region} for company {companyId}.
        slots:
          customerCode: path.customerCode
          country: path.country
          region: path.region
          companyId: path.companyId
      - text: Check whether customer {customerCode} has a valid certificate for region {region}.
        slots:
          customerCode: path.customerCode
          region: path.region
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/customers/{customerCode}/attributes/unlink'].put
  update:
    x-apievangelist-phrasing:
      intent: Unlink attributes from a customer
      effect: write
      questions:
      - How do I detach attributes from a customer?
      - Can I unlink several customer attributes in one request?
      instructions:
      - text: Unlink attributes from customer {customerCode} in company {companyId}.
        slots:
          customerCode: path.customerCode
          companyId: path.companyId
      - text: Remove attribute links from customer {customerCode}.
        slots:
          customerCode: path.customerCode
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/customers/{customerCode}/certificates/unlink'].post
  update:
    x-apievangelist-phrasing:
      intent: Unlink exemption certificates from a customer
      effect: write
      questions:
      - How do I detach an exemption certificate from a customer without deleting it?
      - Can I unlink several certificates from one customer at once?
      instructions:
      - text: Unlink certificates from customer {customerCode} in company {companyId}.
        slots:
          customerCode: path.customerCode
          companyId: path.companyId
      - text: Detach exemption certificates from customer {customerCode}.
        slots:
          customerCode: path.customerCode
      method: generated
      generated: '2026-10-01'