openapi: 3.0.3
info:
  title: SmartRecruiters Candidate Applications Jobs API
  description: The SmartRecruiters Candidate API enables customers to import, export, read, and update candidate data. Provides full candidate profile management including personal information, application history, notes, and attachments.
  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: []
tags:
- name: Jobs
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
      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
      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:
  schemas:
    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
    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
    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
    JobListResult:
      type: object
      properties:
        limit:
          type: integer
        offset:
          type: integer
        totalFound:
          type: integer
        content:
          type: array
          items:
            $ref: '#/components/schemas/Job'
    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
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-SmartToken
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://www.smartrecruiters.com/identity/oauth/token
          scopes:
            candidates.read: Read candidate data
            candidates.write: Write candidate data