# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Hris API
  version: 1.0.0
extends: openapi/merge-hris-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: 5
- target: $.paths['/hris/v1/field-mappings'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an HRIS field mapping
      effect: write
      questions:
      - Can I map a custom field from a customer's HR system onto the Employee model?
      - Will adding a field mapping force a full resync of the linked account?
      - Can I transform the remote value with an expression when mapping it?
      instructions:
      - text: Map remote field {remote_field_traversal_path} from {remote_method} {remote_url_path} onto {common_model_name}.
        slots:
          remote_field_traversal_path: requestBody.remote_field_traversal_path
          remote_method: requestBody.remote_method
          remote_url_path: requestBody.remote_url_path
          common_model_name: requestBody.common_model_name
      - text: Create a field mapping into target field {target_field_name} on {common_model_name} for account {account_token}.
        slots:
          target_field_name: requestBody.target_field_name
          common_model_name: requestBody.common_model_name
          account_token: header.X-Account-Token
      method: generated
      generated: '2026-09-26'
- target: $.paths['/hris/v1/field-mappings/{field_mapping_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an HRIS field mapping
      effect: destructive
      questions:
      - What happens to already-synced data when I remove a field mapping?
      - Can I delete a custom HR field mapping I set up for one linked account?
      instructions:
      - text: Delete field mapping {field_mapping_id}.
        slots:
          field_mapping_id: path.field_mapping_id
      - text: Remove field mapping {field_mapping_id} from linked account {account_token}.
        slots:
          field_mapping_id: path.field_mapping_id
          account_token: header.X-Account-Token
      method: generated
      generated: '2026-09-26'
- target: $.paths['/hris/v1/field-mappings/{field_mapping_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an HRIS field mapping
      effect: write
      questions:
      - Can I point an existing field mapping at a different remote field path?
      - Is it possible to change the transform expression on a mapping I already made?
      instructions:
      - text: Change field mapping {field_mapping_id} to read {remote_field_traversal_path}.
        slots:
          field_mapping_id: path.field_mapping_id
          remote_field_traversal_path: requestBody.remote_field_traversal_path
      - text: Set the mapping expression of {field_mapping_id} to {advanced_mapping_expression}.
        slots:
          field_mapping_id: path.field_mapping_id
          advanced_mapping_expression: requestBody.advanced_mapping_expression
      method: generated
      generated: '2026-09-26'
- target: $.paths['/hris/v1/remote-fields'].get
  update:
    x-apievangelist-phrasing:
      intent: List remote fields available for mapping
      effect: read
      questions:
      - Which third-party fields in a customer's HR system can I map or override?
      - Can I see example values for remote fields before mapping them?
      instructions:
      - text: List remote fields for linked account {account_token}.
        slots:
          account_token: header.X-Account-Token
      - text: Show remote fields for {common_models} with example values.
        slots:
          common_models: query.common_models
      method: generated
      generated: '2026-09-26'
- target: $.paths['/hris/v1/target-fields'].get
  update:
    x-apievangelist-phrasing:
      intent: List organization-wide HRIS target fields
      effect: read
      questions:
      - What organization-wide target fields have been added to the HR Common Models?
      - Does the target fields list include ones specific to a single linked account?
      instructions:
      - text: List org-wide target fields for account {account_token}.
        slots:
          account_token: header.X-Account-Token
      - text: Show the custom target fields appended across all HRIS linked accounts.
      method: generated
      generated: '2026-09-26'