openapi: 3.1.0
info:
  title: Greenhouse Candidate Ingestion API
  description: |
    The Candidate Ingestion API (a.k.a. the Partner API) lets sourcing partners create
    candidates and prospects in a customer's Greenhouse account, list visible jobs and
    prospect pools, fetch the current user, and generate branded tracking links.
    Authentication is OAuth 2.0 (Authorization Code or Client Credentials) or HTTP Basic
    with a Partner API key plus an On-Behalf-Of header carrying a Greenhouse user email.
  version: "1.0.0"
  contact:
    name: Greenhouse Software
    url: https://www.greenhouse.com
    email: developers@greenhouse.io
servers:
  - url: https://api.greenhouse.io/v1/partner
    description: Production Partner API

security:
  - OAuth2: [partner]
  - BasicAuth: []

tags:
  - name: Candidates
    description: Create or retrieve candidates / prospects in the customer's Greenhouse account.
  - name: Jobs
    description: List jobs visible to the integrated user.
  - name: ProspectPools
    description: Read configured prospect pools and their stages.
  - name: Users
    description: Inspect the current authenticated user.
  - name: TrackingLinks
    description: Generate branded tracking links for sourcing campaigns.

paths:
  /candidates:
    get:
      tags: [Candidates]
      summary: List Partner Candidates
      description: Retrieve candidates by partner-supplied external IDs or Greenhouse IDs.
      operationId: listPartnerCandidates
      parameters:
        - name: external_ids
          in: query
          schema:
            type: array
            items: { type: string }
          style: form
          explode: false
        - name: candidate_ids
          in: query
          schema:
            type: array
            items: { type: integer }
          style: form
          explode: false
        - $ref: '#/components/parameters/OnBehalfOf'
      responses:
        '200':
          description: Partner candidates.
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/PartnerCandidate' }
    post:
      tags: [Candidates]
      summary: Create Partner Candidate
      description: Create a candidate or prospect on behalf of a Greenhouse user.
      operationId: createPartnerCandidate
      parameters: [ { $ref: '#/components/parameters/OnBehalfOf' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/PartnerCandidate' }
      responses:
        '201':
          description: Created.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/PartnerCandidate' }

  /current_user:
    get:
      tags: [Users]
      summary: Retrieve Current Partner User
      operationId: getCurrentPartnerUser
      parameters: [ { $ref: '#/components/parameters/OnBehalfOf' } ]
      responses:
        '200':
          description: Current user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id: { type: integer }
                  name: { type: string }
                  email: { type: string, format: email }

  /jobs:
    get:
      tags: [Jobs]
      summary: List Partner Jobs
      description: List jobs visible to the integrated user.
      operationId: listPartnerJobs
      parameters: [ { $ref: '#/components/parameters/OnBehalfOf' } ]
      responses:
        '200':
          description: Visible jobs.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id: { type: integer }
                    name: { type: string }
                    requisition_id: { type: string, nullable: true }
                    departments:
                      type: array
                      items: { type: object }
                    offices:
                      type: array
                      items: { type: object }

  /prospect_pools:
    get:
      tags: [ProspectPools]
      summary: List Partner Prospect Pools
      operationId: listPartnerProspectPools
      parameters: [ { $ref: '#/components/parameters/OnBehalfOf' } ]
      responses:
        '200':
          description: Prospect pools.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id: { type: integer }
                    name: { type: string }
                    stages:
                      type: array
                      items:
                        type: object
                        properties:
                          id: { type: integer }
                          name: { type: string }
                          priority: { type: integer }

  /tracking_link:
    post:
      tags: [TrackingLinks]
      summary: Create Tracking Link
      description: Generate a branded tracking link tied to the partner and an optional job.
      operationId: createTrackingLink
      parameters: [ { $ref: '#/components/parameters/OnBehalfOf' } ]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                job_id: { type: integer }
                source_id: { type: integer }
                external_id: { type: string }
      responses:
        '201':
          description: Tracking link.
          content:
            application/json:
              schema:
                type: object
                properties:
                  url: { type: string, format: uri }
                  expires_at: { type: string, format: date-time }

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.greenhouse.io/oauth/authorize
          tokenUrl: https://app.greenhouse.io/oauth/token
          scopes:
            partner: Partner integration scope.
        clientCredentials:
          tokenUrl: https://app.greenhouse.io/oauth/token
          scopes:
            partner: Partner integration scope.
    BasicAuth:
      type: http
      scheme: basic
      description: HTTP Basic with the Partner API key as the username and an empty password.

  parameters:
    OnBehalfOf:
      name: On-Behalf-Of
      in: header
      required: true
      description: Email of the Greenhouse user the request is made on behalf of (Basic auth) or implied from the OAuth token.
      schema: { type: string, format: email }

  schemas:
    PartnerCandidate:
      type: object
      required: [external_id, first_name, last_name]
      properties:
        external_id:
          type: string
          description: Partner-system identifier for this candidate.
        first_name: { type: string }
        last_name: { type: string }
        company: { type: string }
        title: { type: string }
        emails:
          type: array
          items:
            type: object
            properties:
              value: { type: string, format: email }
              type: { type: string }
        phone_numbers:
          type: array
          items:
            type: object
            properties:
              value: { type: string }
              type: { type: string }
        social_media_addresses:
          type: array
          items:
            type: object
            properties:
              value: { type: string }
        application:
          type: object
          properties:
            job_id: { type: integer }
            initial_stage_id: { type: integer }
            source_id: { type: integer }
            referrer:
              type: object
              properties:
                type: { type: string }
                value: { type: string }
        prospect:
          type: object
          properties:
            prospect_pool_id: { type: integer }
            prospect_stage_id: { type: integer }
            prospect_owner_id: { type: integer }
        attachments:
          type: array
          items:
            type: object
            properties:
              filename: { type: string }
              type: { type: string, enum: [resume, cover_letter, admin_only, public, offer_letter] }
              content: { type: string }
              content_type: { type: string }
              url: { type: string, format: uri }