Greenhouse GraphQL API

openapi: 3.2.0
info:
  title: Greenhouse Onboarding Graph QL API
  description: 'The Greenhouse Onboarding (GHO) API is a single GraphQL endpoint exposing employee,

    department, location, custom field, and team data along with mutations for creating

    and updating departments, locations, pending hires, and employee profiles.

    Authentication uses HTTP Basic with an Onboarding Access Key (username) and Secret

    Key (password); only Super Admins can issue or revoke keys. Rate limiting is enforced

    by both request count (100 per window) and per-query complexity (max 2500 points);

    clients should inspect the `rateLimit` GraphQL field to track remaining budget.

    '
  version: 1.0.0
  contact:
    name: Greenhouse Software
    url: https://www.greenhouse.com
    email: developers@greenhouse.io
servers:
- url: https://onboarding-api.greenhouse.io
  description: Onboarding GraphQL endpoint host.
security:
- BasicAuth: []
tags:
- name: GraphQL
  description: Single GraphQL endpoint for all Onboarding operations.
paths:
  /graphql:
    post:
      tags:
      - GraphQL
      summary: Execute Onboarding GraphQL
      description: 'Execute a GraphQL query or mutation against the Greenhouse Onboarding schema.

        Supported root queries include `employee(id)`, `employees`, `departments`,

        `locations`, `customFields`, `teams`, and `rateLimit`. Supported mutations

        include department / location CRUD, `addPendingHire`, and `updateEmployeeProfile`.

        Errors use the GraphQL `errors` array with codes: Authentication, Validation,

        NotFound, Server, RateLimit.

        '
      operationId: executeOnboardingGraphQL
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GraphQLRequest'
      responses:
        '200':
          description: GraphQL response (errors carried inside the body).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphQLResponse'
        '401':
          description: Authentication failed.
        '429':
          description: Rate or complexity limit exceeded.
  /graphql/introspection:
    get:
      tags:
      - GraphQL
      summary: Onboarding GraphQL Schema (Documentation Pointer)
      description: 'GraphQL schema is discovered via introspection by POSTing a standard introspection

        query to /graphql. This path is documentation-only and not an additional HTTP route.

        '
      operationId: getOnboardingIntrospectionDocs
      responses:
        '200':
          description: See documentation.
components:
  schemas:
    GraphQLResponse:
      type: object
      properties:
        data:
          type: object
          additionalProperties: true
          nullable: true
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
              path:
                type: array
                items:
                  type: string
              extensions:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                    - Authentication
                    - Validation
                    - NotFound
                    - Server
                    - RateLimit
        extensions:
          type: object
          properties:
            rateLimit:
              type: object
              properties:
                cost:
                  type: integer
                remaining:
                  type: integer
                resetAt:
                  type: string
                  format: date-time
    GraphQLRequest:
      type: object
      required:
      - query
      properties:
        query:
          type: string
        operationName:
          type: string
        variables:
          type: object
          additionalProperties: true
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: HTTP Basic with the Onboarding Access Key as username and Secret Key as password.