openapi: 3.0.3
info:
  title: SmartRecruiters Candidate Applications Postings 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: Postings
paths:
  /v1/companies/{companyIdentifier}/postings:
    get:
      operationId: listPostings
      summary: List Job Postings
      description: Returns a paginated list of active job postings published by a company. Supports filtering by keyword, location, department, and custom fields.
      tags:
      - Postings
      parameters:
      - name: companyIdentifier
        in: path
        required: true
        description: The company identifier as it appears at the end of the default career site URL
        schema:
          type: string
      - name: q
        in: query
        required: false
        description: Full-text search query across job title and description
        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: country
        in: query
        required: false
        description: Filter by country code (ISO 3166-1 alpha-2)
        schema:
          type: string
      - name: region
        in: query
        required: false
        description: Filter by region or state name
        schema:
          type: string
      - name: city
        in: query
        required: false
        description: Filter by city name
        schema:
          type: string
      - name: department
        in: query
        required: false
        description: Filter by department name
        schema:
          type: string
      - name: language
        in: query
        required: false
        description: Filter postings by language code (e.g., en, fr, de)
        schema:
          type: string
      responses:
        '200':
          description: List of job postings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostingListResult'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Company not found
        '429':
          description: Too many requests
  /v1/companies/{companyIdentifier}/postings/{postingId}:
    get:
      operationId: getPosting
      summary: Get Job Posting
      description: Retrieves detailed information about a specific job posting including full job description, qualifications, company description, and location details.
      tags:
      - Postings
      parameters:
      - name: companyIdentifier
        in: path
        required: true
        description: The company identifier
        schema:
          type: string
      - name: postingId
        in: path
        required: true
        description: The unique posting ID or UUID
        schema:
          type: string
      responses:
        '200':
          description: Job posting details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostingDetails'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Posting not found
components:
  schemas:
    EmploymentType:
      type: object
      properties:
        id:
          type: string
        label:
          type: string
    Function:
      type: object
      properties:
        id:
          type: string
        label:
          type: string
    Location:
      type: object
      properties:
        country:
          type: string
          description: ISO 3166-1 alpha-2 country code
        countryCode:
          type: string
        region:
          type: string
        city:
          type: string
        address:
          type: string
        postalCode:
          type: string
        remote:
          type: boolean
          description: Whether the position is remote
    PostingDetails:
      allOf:
      - $ref: '#/components/schemas/Posting'
      - type: object
        properties:
          jobAd:
            type: object
            properties:
              sections:
                type: object
                properties:
                  companyDescription:
                    type: object
                    properties:
                      title:
                        type: string
                      text:
                        type: string
                  jobDescription:
                    type: object
                    properties:
                      title:
                        type: string
                      text:
                        type: string
                  qualifications:
                    type: object
                    properties:
                      title:
                        type: string
                      text:
                        type: string
                  additionalInformation:
                    type: object
                    properties:
                      title:
                        type: string
                      text:
                        type: string
          questionnaire:
            type: object
            properties:
              id:
                type: string
              questions:
                type: array
                items:
                  $ref: '#/components/schemas/Question'
          language:
            type: string
            description: Language of the posting
    Question:
      type: object
      properties:
        id:
          type: string
        required:
          type: boolean
        label:
          type: string
        type:
          type: string
          enum:
          - TEXT
          - SINGLE_SELECT
          - MULTI_SELECT
          - DATE
          - NUMBER
          - BOOLEAN
        answerOptions:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              label:
                type: string
    PostingListResult:
      type: object
      properties:
        limit:
          type: integer
          description: Maximum number of results returned
        offset:
          type: integer
          description: Number of results skipped
        totalFound:
          type: integer
          description: Total number of matching postings
        content:
          type: array
          items:
            $ref: '#/components/schemas/Posting'
    CompanySummary:
      type: object
      properties:
        identifier:
          type: string
        name:
          type: string
    Department:
      type: object
      properties:
        id:
          type: string
        label:
          type: string
    ExperienceLevel:
      type: object
      properties:
        id:
          type: string
        label:
          type: string
    Posting:
      type: object
      properties:
        id:
          type: string
          description: Unique posting identifier
        uuid:
          type: string
          description: Universal unique identifier for the posting
        title:
          type: string
          description: Job title
        department:
          $ref: '#/components/schemas/Department'
        location:
          $ref: '#/components/schemas/Location'
        releasedDate:
          type: string
          format: date-time
          description: Date when the posting was released
        applyUrl:
          type: string
          format: uri
          description: URL to apply for the position
        industry:
          $ref: '#/components/schemas/Industry'
        function:
          $ref: '#/components/schemas/Function'
        experienceLevel:
          $ref: '#/components/schemas/ExperienceLevel'
        employmentType:
          $ref: '#/components/schemas/EmploymentType'
        company:
          $ref: '#/components/schemas/CompanySummary'
    Industry:
      type: object
      properties:
        id:
          type: string
        label:
          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