# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Remote Employments API
  version: 1.0.0
extends: openapi/remote-com-employments-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: 7
- target: $.paths['/employments'].get
  update:
    x-apievangelist-phrasing:
      intent: List employments
      effect: read
      questions:
      - Who is currently employed or contracted through my company on Remote?
      - Can I filter employments by status, employment type or model?
      - How do I find an employment by the person's email?
      instructions:
      - text: List employments with status {status}.
        slots:
          status: query.status
      - text: Find the employment for {email}.
        slots:
          email: query.email
      - text: Show {employment_model} employments of type {employment_type}.
        slots:
          employment_model: query.employment_model
          employment_type: query.employment_type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/employments'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new employment
      effect: write
      questions:
      - How do I start hiring someone in another country through Remote?
      - What details are required to create an employment for a new hire?
      instructions:
      - text: Create an employment for {full_name} ({personal_email}) in {country_code} as {employment_type}.
        slots:
          full_name: requestBody.full_name
          personal_email: requestBody.personal_email
          country_code: requestBody.country_code
          employment_type: requestBody.employment_type
      - text: Hire {full_name} as {job_title} in {country_code}, type {employment_type}, email {personal_email}, starting {provisional_start_date}.
        slots:
          full_name: requestBody.full_name
          job_title: requestBody.job_title
          country_code: requestBody.country_code
          employment_type: requestBody.employment_type
          personal_email: requestBody.personal_email
          provisional_start_date: requestBody.provisional_start_date
      method: generated
      generated: '2026-09-26'
- target: $.paths['/employments/{employment_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an employment's details
      effect: read
      questions:
      - What's the current status and job info for one employee?
      - How do I pull up a single employment record?
      instructions:
      - text: Show employment {employment_id}.
        slots:
          employment_id: path.employment_id
      - text: Get the details of employment {employment_id}.
        slots:
          employment_id: path.employment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/employments/{employment_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an employee's job, manager or department
      effect: write
      questions:
      - Can I change an employee's manager or department?
      - How do I update someone's job title or work email?
      instructions:
      - text: Change the job title of employment {employment_id} to {job_title}.
        slots:
          employment_id: path.employment_id
          job_title: requestBody.job_title
      - text: Move employment {employment_id} to department {department_id} under manager {manager_id}.
        slots:
          employment_id: path.employment_id
          department_id: requestBody.department_id
          manager_id: requestBody.manager_id
      - text: Set the work email of employment {employment_id} to {work_email}.
        slots:
          employment_id: path.employment_id
          work_email: requestBody.work_email
      method: generated
      generated: '2026-09-26'
- target: $.paths['/employments/{employment_id}/invite'].post
  update:
    x-apievangelist-phrasing:
      intent: Invite a hire to self-serve onboarding
      effect: write
      questions:
      - How do I send a new hire the invitation to complete their own onboarding?
      - Can the employee fill in their onboarding details themselves?
      instructions:
      - text: Invite employment {employment_id} to self-serve onboarding.
        slots:
          employment_id: path.employment_id
      - text: Send the onboarding invite to employment {employment_id}.
        slots:
          employment_id: path.employment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/employments/{employment_id}/administrative_details'].get
  update:
    x-apievangelist-phrasing:
      intent: View an employee's administrative details
      effect: read
      questions:
      - Where do I see an employee's administrative details on file?
      - What administrative information does Remote hold for an employment?
      instructions:
      - text: Show the administrative details of employment {employment_id}.
        slots:
          employment_id: path.employment_id
      - text: Get administrative info for employment {employment_id}.
        slots:
          employment_id: path.employment_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/employments/{employment_id}/administrative_details'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an employee's administrative details
      effect: write
      questions:
      - Can I correct or replace an employee's administrative details?
      - How do I submit administrative details for a new employment?
      instructions:
      - text: Update the administrative details of employment {employment_id}.
        slots:
          employment_id: path.employment_id
      - text: Replace the administrative info on file for employment {employment_id}.
        slots:
          employment_id: path.employment_id
      method: generated
      generated: '2026-09-26'