Indeed Employer API — Candidates

naftiko: 1.0.0-alpha2
info:
  label: Indeed Employer API — Candidates
  description: 'Indeed Employer API — Candidates. 3 operations. Lead operation: Indeed List Candidates for an Employer. Self-contained
    Naftiko capability covering one Indeed business surface.'
  tags:
  - Indeed
  - Candidates
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    INDEED_API_KEY: INDEED_API_KEY
capability:
  consumes:
  - type: http
    namespace: employer-candidates
    baseUri: https://apis.indeed.com
    description: Indeed Employer API — Candidates business capability. Self-contained, no shared references.
    resources:
    - name: v1-employers-employerId-candidates
      path: /v1/employers/{employerId}/candidates
      operations:
      - name: listcandidates
        method: GET
        description: Indeed List Candidates for an Employer
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: employerId
          in: path
          type: string
          description: The unique identifier of the employer.
          required: true
        - name: status
          in: query
          type: string
          description: Filter candidates by application status.
        - name: jobPostingId
          in: query
          type: string
          description: Filter candidates by job posting ID.
        - name: after
          in: query
          type: string
          description: Cursor for forward pagination.
        - name: first
          in: query
          type: integer
          description: Number of candidates to return (max 100).
        - name: since
          in: query
          type: string
          description: Return only candidates who applied after this timestamp.
    - name: v1-employers-employerId-candidates-candidateId
      path: /v1/employers/{employerId}/candidates/{candidateId}
      operations:
      - name: getcandidate
        method: GET
        description: Indeed Retrieve a Candidate
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: employerId
          in: path
          type: string
          description: The unique identifier of the employer.
          required: true
        - name: candidateId
          in: path
          type: string
          description: The unique identifier of the candidate application.
          required: true
    - name: v1-employers-employerId-candidates-candidateId-disposition
      path: /v1/employers/{employerId}/candidates/{candidateId}/disposition
      operations:
      - name: updatecandidatedisposition
        method: PUT
        description: Indeed Update Candidate Disposition
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: employerId
          in: path
          type: string
          description: The unique identifier of the employer.
          required: true
        - name: candidateId
          in: path
          type: string
          description: The unique identifier of the candidate application.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    authentication:
      type: bearer
      token: '{{env.INDEED_API_KEY}}'
  exposes:
  - type: rest
    namespace: employer-candidates-rest
    port: 8080
    description: REST adapter for Indeed Employer API — Candidates. One Spectral-compliant resource per consumed operation,
      prefixed with /v1.
    resources:
    - path: /v1/v1/employers/{employerid}/candidates
      name: v1-employers-employerid-candidates
      description: REST surface for v1-employers-employerId-candidates.
      operations:
      - method: GET
        name: listcandidates
        description: Indeed List Candidates for an Employer
        call: employer-candidates.listcandidates
        with:
          employerId: rest.employerId
          status: rest.status
          jobPostingId: rest.jobPostingId
          after: rest.after
          first: rest.first
          since: rest.since
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/employers/{employerid}/candidates/{candidateid}
      name: v1-employers-employerid-candidates-candidateid
      description: REST surface for v1-employers-employerId-candidates-candidateId.
      operations:
      - method: GET
        name: getcandidate
        description: Indeed Retrieve a Candidate
        call: employer-candidates.getcandidate
        with:
          employerId: rest.employerId
          candidateId: rest.candidateId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v1/employers/{employerid}/candidates/{candidateid}/disposition
      name: v1-employers-employerid-candidates-candidateid-disposition
      description: REST surface for v1-employers-employerId-candidates-candidateId-disposition.
      operations:
      - method: PUT
        name: updatecandidatedisposition
        description: Indeed Update Candidate Disposition
        call: employer-candidates.updatecandidatedisposition
        with:
          employerId: rest.employerId
          candidateId: rest.candidateId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: employer-candidates-mcp
    port: 9090
    transport: http
    description: MCP adapter for Indeed Employer API — Candidates. One tool per consumed operation, routed inline through
      this capability's consumes block.
    tools:
    - name: indeed-list-candidates-employer
      description: Indeed List Candidates for an Employer
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: employer-candidates.listcandidates
      with:
        employerId: tools.employerId
        status: tools.status
        jobPostingId: tools.jobPostingId
        after: tools.after
        first: tools.first
        since: tools.since
      outputParameters:
      - type: object
        mapping: $.
    - name: indeed-retrieve-candidate
      description: Indeed Retrieve a Candidate
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: employer-candidates.getcandidate
      with:
        employerId: tools.employerId
        candidateId: tools.candidateId
      outputParameters:
      - type: object
        mapping: $.
    - name: indeed-update-candidate-disposition
      description: Indeed Update Candidate Disposition
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: employer-candidates.updatecandidatedisposition
      with:
        employerId: tools.employerId
        candidateId: tools.candidateId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.