# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Bindbee Candidate API
  version: 1.0.0
extends: openapi/bindbee-candidate-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['/api/ats/v1/candidates'].get
  update:
    x-apievangelist-phrasing:
      intent: Search candidates in the ATS
      effect: read
      questions:
      - Can I find a candidate in our ATS by email address?
      - Which candidates carry a certain tag or work at a given company?
      - What candidates were updated since my last sync?
      instructions:
      - text: Find candidates with email {email}.
        slots:
          email: query.email_addresses
      - text: List candidates named {first_name} {last_name}.
        slots:
          first_name: query.first_name
          last_name: query.last_name
      - text: Show candidates tagged {tag}.
        slots:
          tag: query.tag
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/ats/v1/candidates'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a new candidate to the ATS
      effect: write
      questions:
      - How do I create a candidate profile in the connected ATS?
      - Can I add candidates through one unified endpoint regardless of ATS?
      instructions:
      - text: Create a new candidate in the ATS for connector {connector}.
        slots:
          connector: header.x-connector-token
      - text: Add a candidate profile to our applicant tracking system.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/ats/v1/candidates/create/meta'].get
  update:
    x-apievangelist-phrasing:
      intent: Get fields required to create a candidate
      effect: read
      questions:
      - Which fields does this ATS require before I can create a candidate?
      - What does the create-candidate request body need to look like for a given integration?
      instructions:
      - text: Show the required create-candidate fields for connector {connector}.
        slots:
          connector: header.x-connector-token
      - text: Describe the request body needed to add a candidate.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/ats/v1/candidates/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one candidate by id
      effect: read
      questions:
      - What profile details are stored for one candidate?
      - Can I expand related applications when fetching a candidate?
      instructions:
      - text: Get candidate {id}.
        slots:
          id: path.id
      - text: Retrieve candidate {id} and expand {expand}.
        slots:
          id: path.id
          expand: query.expand
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/ats/v1/candidates/{candidate_id}/attachments'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a file to a candidate
      effect: write
      questions:
      - How do I upload a resume to a specific candidate?
      - Can I attach a file by URL instead of sending the content?
      instructions:
      - text: Upload {file_name} from {file_url} to candidate {candidate_id}.
        slots:
          file_name: requestBody.file_name
          file_url: requestBody.file_url
          candidate_id: path.candidate_id
      - text: Attach a {attachment_type} file named {file_name} to candidate {candidate_id}.
        slots:
          attachment_type: requestBody.attachment_type
          file_name: requestBody.file_name
          candidate_id: path.candidate_id
      method: generated
      generated: '2026-09-26'