openapi: 3.1.0
info:
  title: Greenhouse Job Board API
  description: |
    The Job Board API exposes a customer's public career site data — jobs, departments,
    and offices — and accepts application submissions on POST. GET endpoints are
    unauthenticated; POST application endpoints accept multipart/form-data or JSON and
    require HTTP Basic auth with a Job Board API key.
  version: "1.0.0"
  contact:
    name: Greenhouse Software
    url: https://www.greenhouse.com
    email: developers@greenhouse.io
servers:
  - url: https://boards-api.greenhouse.io/v1/boards/{board_token}
    description: Public Job Board API
    variables:
      board_token:
        default: example
        description: The customer's unique board token (e.g. "exampleco").

tags:
  - name: Jobs
    description: Public job listings.
  - name: Departments
    description: Public department listings.
  - name: Offices
    description: Public office listings.
  - name: Applications
    description: Submit applications to a job.

paths:
  /jobs:
    get:
      tags: [Jobs]
      summary: List Job Board Jobs
      description: Returns the list of public job listings for a board.
      operationId: listBoardJobs
      parameters:
        - name: content
          in: query
          description: When true, includes the full job description content.
          schema: { type: boolean }
      responses:
        '200':
          description: Job listings.
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobs:
                    type: array
                    items: { $ref: '#/components/schemas/BoardJob' }
                  meta:
                    type: object
                    properties:
                      total: { type: integer }

  /jobs/{id}:
    get:
      tags: [Jobs]
      summary: Retrieve Job Board Job
      operationId: getBoardJob
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
        - name: questions
          in: query
          schema: { type: boolean }
      responses:
        '200':
          description: Job listing.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BoardJob' }

    post:
      tags: [Applications]
      summary: Submit Application
      description: Submit a candidate application to a job posting. Accepts multipart/form-data or JSON. Requires Basic auth.
      operationId: submitApplication
      security:
        - BasicAuth: []
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/ApplicationSubmission' }
          multipart/form-data:
            schema: { $ref: '#/components/schemas/ApplicationSubmission' }
      responses:
        '200':
          description: Application accepted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success: { type: string }

  /departments:
    get:
      tags: [Departments]
      summary: List Job Board Departments
      operationId: listBoardDepartments
      parameters:
        - name: render_as
          in: query
          schema: { type: string, enum: [list, tree], default: list }
      responses:
        '200':
          description: Departments.
          content:
            application/json:
              schema:
                type: object
                properties:
                  departments:
                    type: array
                    items: { $ref: '#/components/schemas/BoardDepartment' }

  /departments/{id}:
    get:
      tags: [Departments]
      summary: Retrieve Job Board Department
      operationId: getBoardDepartment
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        '200':
          description: Department.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BoardDepartment' }

  /offices:
    get:
      tags: [Offices]
      summary: List Job Board Offices
      operationId: listBoardOffices
      parameters:
        - name: render_as
          in: query
          schema: { type: string, enum: [list, tree], default: list }
      responses:
        '200':
          description: Offices.
          content:
            application/json:
              schema:
                type: object
                properties:
                  offices:
                    type: array
                    items: { $ref: '#/components/schemas/BoardOffice' }

  /offices/{id}:
    get:
      tags: [Offices]
      summary: Retrieve Job Board Office
      operationId: getBoardOffice
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        '200':
          description: Office.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BoardOffice' }

components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: HTTP Basic auth using the Job Board API key as the username with an empty password.

  schemas:
    BoardJob:
      type: object
      properties:
        id: { type: integer }
        title: { type: string }
        updated_at: { type: string, format: date-time }
        location:
          type: object
          properties:
            name: { type: string }
        absolute_url: { type: string, format: uri }
        internal_job_id: { type: integer }
        company_name: { type: string }
        first_published: { type: string, format: date-time }
        requisition_id: { type: string, nullable: true }
        data_compliance:
          type: array
          items:
            type: object
            properties:
              type: { type: string }
              requires_consent: { type: boolean }
              retention_period: { type: integer, nullable: true }
        metadata:
          type: array
          items: { type: object }
        departments:
          type: array
          items: { $ref: '#/components/schemas/BoardDepartment' }
        offices:
          type: array
          items: { $ref: '#/components/schemas/BoardOffice' }
        content: { type: string }

    BoardDepartment:
      type: object
      properties:
        id: { type: integer }
        name: { type: string }
        parent_id: { type: integer, nullable: true }
        child_ids: { type: array, items: { type: integer } }
        jobs:
          type: array
          items: { $ref: '#/components/schemas/BoardJob' }

    BoardOffice:
      type: object
      properties:
        id: { type: integer }
        name: { type: string }
        location: { type: string }
        parent_id: { type: integer, nullable: true }
        child_ids: { type: array, items: { type: integer } }
        departments:
          type: array
          items: { $ref: '#/components/schemas/BoardDepartment' }

    ApplicationSubmission:
      type: object
      required: [first_name, last_name, email]
      properties:
        first_name: { type: string }
        last_name: { type: string }
        email: { type: string, format: email }
        phone: { type: string }
        location:
          type: string
          description: City, State / Country.
        resume_text: { type: string }
        resume_text_file: { type: string, description: Base64-encoded resume file content. }
        resume_content_filename: { type: string }
        resume_content_type: { type: string }
        cover_letter_text: { type: string }
        cover_letter_content: { type: string, description: Base64-encoded cover letter. }
        cover_letter_content_filename: { type: string }
        question_id:
          type: string
          description: Greenhouse-defined custom question identifiers; multiple entries allowed.