openapi: 3.0.3
info:
  title: SmartRecruiters Job API
  description: >-
    The SmartRecruiters Job API enables customers to extract and import job data,
    supporting full job lifecycle management. Create, update, list, and manage jobs
    including their status, departments, hiring teams, and custom fields.
  version: 1.0.0
  contact:
    name: SmartRecruiters Developer Support
    url: https://developers.smartrecruiters.com/
servers:
  - url: https://api.smartrecruiters.com
    description: SmartRecruiters Production API
security:
  - ApiKey: []
paths:
  /jobs:
    get:
      operationId: listJobs
      summary: List Jobs
      description: >-
        Returns a paginated list of jobs. Supports filtering by status, department,
        location, hiring manager, and other criteria.
      tags:
        - Jobs
      parameters:
        - name: q
          in: query
          required: false
          description: Full-text search query
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Maximum number of results to return
          schema:
            type: integer
            default: 10
            maximum: 100
        - name: offset
          in: query
          required: false
          description: Number of results to skip for pagination
          schema:
            type: integer
            default: 0
        - name: status
          in: query
          required: false
          description: Filter by job status
          schema:
            type: string
            enum:
              - CREATED
              - SOURCING
              - INTERVIEW
              - OFFER
              - HIRED
              - CANCELLED
        - name: department
          in: query
          required: false
          description: Filter by department ID
          schema:
            type: string
      responses:
        '200':
          description: List of jobs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobListResult'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '429':
          description: Too many requests
    post:
      operationId: createJob
      summary: Create Job
      description: Creates a new job in the SmartRecruiters system.
      tags:
        - Jobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobCreate'
      responses:
        '201':
          description: Job created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden

  /jobs/{jobId}:
    get:
      operationId: getJob
      summary: Get Job
      description: Retrieves detailed information about a specific job.
      tags:
        - Jobs
      parameters:
        - name: jobId
          in: path
          required: true
          description: The unique job identifier
          schema:
            type: string
      responses:
        '200':
          description: Job details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Job not found
    patch:
      operationId: updateJob
      summary: Update Job
      description: Updates properties of an existing job.
      tags:
        - Jobs
      parameters:
        - name: jobId
          in: path
          required: true
          description: The unique job identifier
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobUpdate'
      responses:
        '200':
          description: Job updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Job not found

  /jobs/{jobId}/status:
    put:
      operationId: updateJobStatus
      summary: Update Job Status
      description: Updates the status of a job, moving it through the hiring workflow.
      tags:
        - Jobs
      parameters:
        - name: jobId
          in: path
          required: true
          description: The unique job identifier
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - status
              properties:
                status:
                  type: string
                  enum:
                    - SOURCING
                    - INTERVIEW
                    - OFFER
                    - HIRED
                    - CANCELLED
      responses:
        '200':
          description: Job status updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Job not found

  /jobs/{jobId}/hiring-team:
    get:
      operationId: getJobHiringTeam
      summary: Get Job Hiring Team
      description: Returns the hiring team members assigned to a specific job.
      tags:
        - Jobs
        - Teams
      parameters:
        - name: jobId
          in: path
          required: true
          description: The unique job identifier
          schema:
            type: string
      responses:
        '200':
          description: Hiring team members
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobOwner:
                    $ref: '#/components/schemas/TeamMember'
                  hiringManagers:
                    type: array
                    items:
                      $ref: '#/components/schemas/TeamMember'
                  recruiters:
                    type: array
                    items:
                      $ref: '#/components/schemas/TeamMember'
                  coordinators:
                    type: array
                    items:
                      $ref: '#/components/schemas/TeamMember'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Job not found

  /jobs/{jobId}/candidates:
    get:
      operationId: listJobCandidates
      summary: List Job Candidates
      description: Returns a paginated list of candidates who have applied to a specific job.
      tags:
        - Jobs
        - Candidates
      parameters:
        - name: jobId
          in: path
          required: true
          description: The unique job identifier
          schema:
            type: string
        - name: status
          in: query
          required: false
          description: Filter by candidate status
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 10
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: List of candidates for the job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CandidateListResult'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Job not found

components:
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-SmartToken
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://www.smartrecruiters.com/identity/oauth/token
          scopes:
            jobs.read: Read job data
            jobs.write: Write job data

  schemas:
    JobListResult:
      type: object
      properties:
        limit:
          type: integer
        offset:
          type: integer
        totalFound:
          type: integer
        content:
          type: array
          items:
            $ref: '#/components/schemas/Job'

    Job:
      type: object
      properties:
        id:
          type: string
          description: Unique job identifier
        title:
          type: string
          description: Job title
        refNumber:
          type: string
          description: External reference number
        createdOn:
          type: string
          format: date-time
        updatedOn:
          type: string
          format: date-time
        status:
          type: string
          enum:
            - CREATED
            - SOURCING
            - INTERVIEW
            - OFFER
            - HIRED
            - CANCELLED
        department:
          type: object
          properties:
            id:
              type: string
            label:
              type: string
        location:
          type: object
          properties:
            id:
              type: string
            city:
              type: string
            country:
              type: string
            region:
              type: string
            remote:
              type: boolean
        industry:
          type: object
          properties:
            id:
              type: string
            label:
              type: string
        function:
          type: object
          properties:
            id:
              type: string
            label:
              type: string
        experienceLevel:
          type: object
          properties:
            id:
              type: string
            label:
              type: string
        typeOfEmployment:
          type: object
          properties:
            id:
              type: string
            label:
              type: string
        hiringTeam:
          type: object
          properties:
            jobOwner:
              $ref: '#/components/schemas/TeamMember'
            hiringManagers:
              type: array
              items:
                $ref: '#/components/schemas/TeamMember'
            recruiters:
              type: array
              items:
                $ref: '#/components/schemas/TeamMember'
        numberOfOpenings:
          type: integer

    JobCreate:
      type: object
      required:
        - title
        - department
        - location
      properties:
        title:
          type: string
        refNumber:
          type: string
        department:
          type: object
          properties:
            id:
              type: string
        location:
          type: object
          properties:
            id:
              type: string
            remote:
              type: boolean
        industry:
          type: object
          properties:
            id:
              type: string
        function:
          type: object
          properties:
            id:
              type: string
        experienceLevel:
          type: object
          properties:
            id:
              type: string
        typeOfEmployment:
          type: object
          properties:
            id:
              type: string
        jobAd:
          type: object
          properties:
            sections:
              type: object
              properties:
                jobDescription:
                  type: object
                  properties:
                    text:
                      type: string
                qualifications:
                  type: object
                  properties:
                    text:
                      type: string

    JobUpdate:
      type: object
      properties:
        title:
          type: string
        refNumber:
          type: string
        department:
          type: object
          properties:
            id:
              type: string

    TeamMember:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email
        role:
          type: string

    CandidateListResult:
      type: object
      properties:
        limit:
          type: integer
        offset:
          type: integer
        totalFound:
          type: integer
        content:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              firstName:
                type: string
              lastName:
                type: string
              email:
                type: string
              status:
                type: string
              appliedOn:
                type: string
                format: date-time