Greenhouse TestDelivery API

openapi: 3.1.0
info:
  title: Greenhouse Assessment Partner ActivityFeed TestDelivery 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: TestDelivery
  description: Sending tests to candidates and reporting status.
paths:
  /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:
  schemas:
    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
  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).