API Evangelist conversational phrasing for Avalara Certificates API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Avalara Certificates API
  version: 1.0.0
extends: openapi/avalara-certificates-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: 22
- target: $.paths['/api/v2/companies/{companyId}/certificates'].get
  update:
    x-apievangelist-phrasing:
      intent: List a company's exemption certificates
      effect: read
      questions:
      - Which exemption certificates are stored under my AvaTax company?
      - Can I filter a company's certificates with an OData expression?
      instructions:
      - text: List exemption certificates for company {companyId}.
        slots:
          companyId: path.companyId
      - text: Show certificates for company {companyId} matching {filter}.
        slots:
          companyId: path.companyId
          filter: query.$filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/companies/{companyId}/certificates'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a certificate under an AvaTax company
      effect: write
      questions:
      - Can I add an exemption certificate directly to a specific AvaTax company?
      - Where do I create certificates scoped to one company ID?
      instructions:
      - text: Create a new exemption certificate under company {companyId}.
        slots:
          companyId: path.companyId
      - text: Add a certificate record to AvaTax company {companyId}.
        slots:
          companyId: path.companyId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/certificates'].get
  update:
    x-apievangelist-phrasing:
      intent: Search exemption certificates by status or customer
      effect: read
      questions:
      - Which exemption certificates are expired across my account?
      - Can I list certificates belonging to one customer ID?
      instructions:
      - text: List certificates with status {status}.
        slots:
          status: query.status
      - text: Show exemption certificates for customer {customerId}, page {page}.
        slots:
          customerId: query.customerId
          page: query.page
      method: generated
      generated: '2026-09-26'
- target: $.paths['/certificates'].post
  update:
    x-apievangelist-phrasing:
      intent: Record an exemption certificate
      effect: write
      questions:
      - How do I record a customer's resale exemption certificate?
      - Can I set an expiration date and exempt percentage on a new certificate?
      instructions:
      - text: Create a certificate with exemption reason {exemptionReason} for exposure zone {exposureZone}.
        slots:
          exemptionReason: requestBody.exemptionReason
          exposureZone: requestBody.exposureZone
      - text: Record certificate {exemptionNumber} for customer {customerCode}, reason {exemptionReason}, zone {exposureZone}.
        slots:
          exemptionNumber: requestBody.exemptionNumber
          customerCode: requestBody.customerCode
          exemptionReason: requestBody.exemptionReason
          exposureZone: requestBody.exposureZone
      method: generated
      generated: '2026-09-26'
- target: $.paths['/certificates/{certificateId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an exemption certificate
      effect: read
      questions:
      - Can I view the details of one exemption certificate by ID?
      - When does a particular certificate expire?
      instructions:
      - text: Get certificate {certificateId}.
        slots:
          certificateId: path.certificateId
      - text: Show the exemption reason and dates on certificate {certificateId}.
        slots:
          certificateId: path.certificateId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/certificates/{certificateId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an exemption certificate
      effect: write
      questions:
      - Can I extend the expiration date on an existing certificate?
      - Is it possible to change the exposure zone of a certificate I already recorded?
      instructions:
      - text: Update certificate {certificateId} with reason {exemptionReason} and zone {exposureZone}.
        slots:
          certificateId: path.certificateId
          exemptionReason: requestBody.exemptionReason
          exposureZone: requestBody.exposureZone
      - text: Set the expiration of certificate {certificateId} to {expirationDate}, keeping reason {exemptionReason} in zone {exposureZone}.
        slots:
          certificateId: path.certificateId
          expirationDate: requestBody.expirationDate
          exemptionReason: requestBody.exemptionReason
          exposureZone: requestBody.exposureZone
      method: generated
      generated: '2026-09-26'
- target: $.paths['/certificates/{certificateId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an exemption certificate
      effect: destructive
      questions:
      - Can I delete an exemption certificate that was entered in error?
      - What happens to a customer's exemption if I remove their certificate?
      instructions:
      - text: Delete certificate {certificateId}.
        slots:
          certificateId: path.certificateId
      - text: Remove the invalid exemption certificate {certificateId}.
        slots:
          certificateId: path.certificateId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/certificates/{certificateId}/attachment'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a certificate attachment
      effect: read
      questions:
      - Can I download the signed PDF of an exemption certificate?
      - Where do I get the scanned image attached to a certificate?
      instructions:
      - text: Download the attachment for certificate {certificateId}.
        slots:
          certificateId: path.certificateId
      - text: Get the PDF of certificate {certificateId}.
        slots:
          certificateId: path.certificateId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/certificates/{certificateId}/attachment'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a certificate attachment
      effect: write
      questions:
      - Can I attach a scanned copy to a certificate record?
      - Is it possible to upload the signed form after creating a certificate?
      instructions:
      - text: Upload {file} as the attachment for certificate {certificateId}.
        slots:
          file: requestBody.file
          certificateId: path.certificateId
      - text: Attach the signed form to certificate {certificateId}.
        slots:
          certificateId: path.certificateId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v2/companies/{companyId}/certificates/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a certificate stored under an AvaTax company
      effect: read
      questions:
      - Can I retrieve one exemption certificate by ID within a specific AvaTax company?
      - What does a company-scoped certificate record show about a customer's exemption?
      instructions:
      - text: Get certificate {id} from AvaTax company {companyId}.
        slots:
          id: path.id
          companyId: path.companyId
      - text: Show company {companyId}'s exemption certificate {id}.
        slots:
          companyId: path.companyId
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/certificates/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a certificate in an AvaTax company
      effect: write
      questions:
      - How do I replace a company-scoped exemption certificate with a corrected version?
      - Does updating a certificate in an AvaTax company overwrite the whole record?
      instructions:
      - text: Replace certificate {id} in AvaTax company {companyId} with the corrected version.
        slots:
          id: path.id
          companyId: path.companyId
      - text: Overwrite company {companyId} certificate {id} with updated details.
        slots:
          companyId: path.companyId
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/certificates/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke and delete a company's certificate
      effect: destructive
      questions:
      - Can I revoke an exemption certificate in an AvaTax company and delete it?
      - Is a company-scoped certificate revoked before it is removed?
      instructions:
      - text: Revoke and delete certificate {id} in AvaTax company {companyId}.
        slots:
          id: path.id
          companyId: path.companyId
      - text: Remove company {companyId}'s certificate {id} after revoking it.
        slots:
          companyId: path.companyId
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/certificates/{id}/attachment'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a company certificate image or PDF
      effect: read
      questions:
      - Can I get a one-page JPEG preview of a certificate stored in my AvaTax company?
      - How do I download the full PDF of a company-scoped certificate?
      instructions:
      - text: Download the image for certificate {id} in AvaTax company {companyId}.
        slots:
          id: path.id
          companyId: path.companyId
      - text: Fetch a preview of company {companyId} certificate {id}.
        slots:
          companyId: path.companyId
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/certificates/{id}/attachment'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload an image to a company's certificate
      effect: write
      questions:
      - Which file formats can I upload as a certificate image in an AvaTax company?
      - Should a multi-page certificate scan be uploaded as a PDF?
      instructions:
      - text: Upload an image to certificate {id} in AvaTax company {companyId}.
        slots:
          id: path.id
          companyId: path.companyId
      - text: Attach a PNG or PDF scan to company {companyId} certificate {id}.
        slots:
          companyId: path.companyId
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/certificates/setup'].get
  update:
    x-apievangelist-phrasing:
      intent: Check if certificate storage is set up
      effect: read
      questions:
      - Is my company configured to use the exemption certificate store?
      - How can I tell whether certificate setup has finished for a company?
      instructions:
      - text: Check certificate setup status for company {companyId}.
        slots:
          companyId: path.companyId
      - text: Confirm whether {companyId} can store exemption certificates yet.
        slots:
          companyId: path.companyId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/certificates/setup'].post
  update:
    x-apievangelist-phrasing:
      intent: Request exemption certificate setup
      effect: write
      questions:
      - How do I enable the exemption certificate document store for my company?
      - Can I request certificate storage before uploading any certificates?
      instructions:
      - text: Request exemption certificate setup for company {companyId}.
        slots:
          companyId: path.companyId
      - text: Turn on the certificate document store for {companyId}.
        slots:
          companyId: path.companyId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/certificates/{id}/attributes/link'].post
  update:
    x-apievangelist-phrasing:
      intent: Link attributes to a certificate
      effect: write
      questions:
      - Can I attach behavior-controlling attributes to an existing certificate?
      - Is it possible to link several attributes to one certificate at once?
      instructions:
      - text: Link attributes to certificate {id} in company {companyId}.
        slots:
          id: path.id
          companyId: path.companyId
      - text: Add these attributes to company {companyId} certificate {id}.
        slots:
          companyId: path.companyId
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/certificates/{id}/customers/link'].post
  update:
    x-apievangelist-phrasing:
      intent: Link customers to a certificate
      effect: write
      questions:
      - How do I let a customer use an exemption certificate on their purchases?
      - Can one certificate cover several customer records?
      instructions:
      - text: Link customers to certificate {id} in company {companyId}.
        slots:
          id: path.id
          companyId: path.companyId
      - text: Connect these customer records to exemption certificate {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/certificates/{id}/attributes'].get
  update:
    x-apievangelist-phrasing:
      intent: List attributes linked to a certificate
      effect: read
      questions:
      - Which attributes are currently linked to a certificate?
      - Can I see what controls a certificate's behavior?
      instructions:
      - text: List attributes on certificate {id} in company {companyId}.
        slots:
          id: path.id
          companyId: path.companyId
      - text: Show the attributes linked to company {companyId} certificate {id}.
        slots:
          companyId: path.companyId
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/certificates/{id}/customers'].get
  update:
    x-apievangelist-phrasing:
      intent: List customers linked to a certificate
      effect: read
      questions:
      - Which customers are covered by a given exemption certificate?
      - Can I see every customer record linked to one certificate?
      instructions:
      - text: List customers linked to certificate {id} in company {companyId}.
        slots:
          id: path.id
          companyId: path.companyId
      - text: Show who can claim exemption under certificate {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/certificates/{id}/attributes/unlink'].post
  update:
    x-apievangelist-phrasing:
      intent: Unlink attributes from a certificate
      effect: write
      questions:
      - Can I detach an attribute from a certificate without deleting the certificate?
      - Is it possible to unlink several attributes from one certificate at once?
      instructions:
      - text: Unlink attributes from certificate {id} in company {companyId}.
        slots:
          id: path.id
          companyId: path.companyId
      - text: Detach these attributes from company {companyId} certificate {id}.
        slots:
          companyId: path.companyId
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/v2/companies/{companyId}/certificates/{id}/customers/unlink'].post
  update:
    x-apievangelist-phrasing:
      intent: Unlink customers from a certificate
      effect: write
      questions:
      - How do I stop a customer from using a certificate for future exemptions?
      - Do past transactions keep their certificate link after I unlink a customer?
      instructions:
      - text: Unlink customers from certificate {id} in company {companyId}.
        slots:
          id: path.id
          companyId: path.companyId
      - text: Disconnect these customer records from exemption certificate {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'