openapi: 3.1.0
info:
  title: Greenhouse Assessment Partner API
  description: |
    The Assessment Partner API defines the contract that assessment vendors implement so
    Greenhouse can list available tests, send a test to a candidate, and retrieve the
    candidate's results. Endpoints are hosted by the partner (not Greenhouse) and are
    secured with HTTP Basic over HTTPS. Greenhouse may also receive PATCH callbacks from
    the partner with completed test status; otherwise it polls `test_status` hourly for
    up to 8 weeks. API keys must be fewer than 171 characters.
  version: "1.0.0"
  contact:
    name: Greenhouse Software
    url: https://www.greenhouse.com
    email: developers@greenhouse.io
servers:
  - url: https://{partner_host}/{base_path}
    description: Partner-hosted endpoint
    variables:
      partner_host:
        default: partner.example.com
      base_path:
        default: greenhouse-assessment

security:
  - BasicAuth: []

tags:
  - name: Tests
    description: Available tests offered by the partner.
  - name: TestDelivery
    description: Sending tests to candidates and reporting status.

paths:
  /list_tests:
    get:
      tags: [Tests]
      summary: List Partner Tests
      description: Returns the catalog of tests this partner offers.
      operationId: listPartnerTests
      responses:
        '200':
          description: Tests.
          content:
            application/json:
              schema:
                type: object
                properties:
                  partner_test_ids:
                    type: array
                    items: { $ref: '#/components/schemas/PartnerTest' }

  /send_test:
    post:
      tags: [TestDelivery]
      summary: Send Test To Candidate
      description: Greenhouse calls this when a candidate reaches the assessment stage; partner returns a unique partner_interview_id.
      operationId: sendPartnerTest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [partner_test_id, candidate]
              properties:
                partner_test_id: { type: string }
                candidate:
                  type: object
                  properties:
                    first_name: { type: string }
                    last_name: { type: string }
                    email: { type: string, format: email }
                    greenhouse_application_id: { type: integer }
                metadata:
                  type: object
                  additionalProperties: true
      responses:
        '200':
          description: Test delivered.
          content:
            application/json:
              schema:
                type: object
                properties:
                  partner_interview_id: { type: string }
                  test_url: { type: string, format: uri }

  /test_status:
    get:
      tags: [TestDelivery]
      summary: Get Test Status
      description: Greenhouse polls hourly (or partner triggers via PATCH) to retrieve completion + results.
      operationId: getPartnerTestStatus
      parameters:
        - name: partner_interview_id
          in: query
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Status.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TestStatus' }

  /response_error:
    post:
      tags: [TestDelivery]
      summary: Report Validation Errors
      description: Greenhouse sends validation error details so the partner can resolve issues.
      operationId: reportPartnerResponseErrors
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                partner_interview_id: { type: string }
                errors:
                  type: array
                  items:
                    type: object
                    properties:
                      code: { type: string }
                      message: { type: string }
      responses:
        '204':
          description: Acknowledged.

components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: HTTP Basic; the API key is Base64-encoded and used as the username (key must be <171 chars).

  schemas:
    PartnerTest:
      type: object
      properties:
        partner_test_id: { type: string }
        partner_test_name: { type: string }
        partner_test_description: { type: string }

    TestStatus:
      type: object
      properties:
        partner_interview_id: { type: string }
        partner_test_id: { type: string }
        status: { type: string, enum: [in_progress, complete, expired, error] }
        partner_score: { type: string }
        partner_profile_url: { type: string, format: uri }
        partner_profile_summary: { type: string }
        partner_score_details:
          type: array
          items:
            type: object
            properties:
              name: { type: string }
              value: { type: string }