openapi: 3.0.3
info:
  title: Spark Hire Account Interviews API
  description: 'The Spark Hire API embeds video interviewing and talent assessment into an applicant tracking system or custom hiring application. It is a RESTful API with JSON responses served under https://api.sparkhire.com/v1.0. It manages jobs, one-way and live video interviews, interview questions and reusable question sets, company users (evaluators) and their integration API keys, candidate share links, and webhook subscriptions for interview and job lifecycle events.


    Authentication uses HTTP Basic: the username is your API key and the password is ignored. API keys are tied to an individual user and respect that user''s permission level. API access is not self-serve - it must be enabled on your account by Spark Hire - but the API reference is fully public. Timestamps are RFC3339. Rate limit is 400 requests per minute; exceeding it returns 429 with an X-Rate-Limit-Try-Again-Seconds header.


    Endpoint paths and behavior below are transcribed from the public Spark Hire API reference at https://docs.sparkhire.com/. Request and response schemas are honestly modeled from the documented resources; exercising them live requires API access enabled by Spark Hire.'
  version: '1.0'
  contact:
    name: Spark Hire
    url: https://www.sparkhire.com
servers:
- url: https://api.sparkhire.com/v1.0
  description: Spark Hire API
security:
- basicAuth: []
tags:
- name: Interviews
  description: One-way and live video interviews.
paths:
  /interviews:
    get:
      operationId: listInterviews
      tags:
      - Interviews
      summary: List interviews
      parameters:
      - $ref: '#/components/parameters/Range'
      - $ref: '#/components/parameters/OrderBy'
      - $ref: '#/components/parameters/StatusFilter'
      - $ref: '#/components/parameters/TypeFilter'
      responses:
        '200':
          description: A list of interviews.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Interview'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createInterview
      tags:
      - Interviews
      summary: Create an interview
      description: Creates a one-way or live interview for a candidate, tied to a job. Triggers the InterviewCreated webhook event.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InterviewInput'
      responses:
        '201':
          description: The created interview.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Interview'
        '400':
          $ref: '#/components/responses/BadRequest'
  /interviews/{uuid}:
    parameters:
    - $ref: '#/components/parameters/Uuid'
    get:
      operationId: getInterview
      tags:
      - Interviews
      summary: Get an interview
      responses:
        '200':
          description: An interview.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Interview'
        '404':
          $ref: '#/components/responses/NotFound'
        '410':
          description: The interview has expired and is no longer available.
    put:
      operationId: updateInterview
      tags:
      - Interviews
      summary: Update an interview
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InterviewInput'
      responses:
        '200':
          description: The updated interview.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Interview'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteInterview
      tags:
      - Interviews
      summary: Delete an interview
      responses:
        '204':
          description: The interview was deleted.
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Interview:
      allOf:
      - $ref: '#/components/schemas/InterviewInput'
      - type: object
        properties:
          uuid:
            type: string
            format: uuid
          status:
            type: string
            description: Lifecycle status - created, accepted, completed, expired, rescheduled, reset, or rated.
          rating:
            type: number
            nullable: true
            description: Reviewer rating captured when the interview is evaluated.
          created_at:
            type: string
            format: date-time
          updated_at:
            type: string
            format: date-time
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
    InterviewInput:
      type: object
      properties:
        job_uuid:
          type: string
          format: uuid
          description: The job this interview belongs to.
        type:
          type: string
          description: The interview type, e.g. one_way or live.
        candidate_first_name:
          type: string
        candidate_last_name:
          type: string
        candidate_email:
          type: string
          format: email
        question_set_uuid:
          type: string
          format: uuid
          nullable: true
          description: Optional question set to apply to the interview.
  parameters:
    Uuid:
      name: uuid
      in: path
      required: true
      description: The UUID of the resource.
      schema:
        type: string
        format: uuid
    OrderBy:
      name: orderby
      in: query
      required: false
      description: Sort order, e.g. title_asc or updated_desc.
      schema:
        type: string
        example: updated_desc
    TypeFilter:
      name: type[]
      in: query
      required: false
      description: Filter by one or more types.
      schema:
        type: array
        items:
          type: string
    Range:
      name: range
      in: query
      required: false
      description: Pagination range, e.g. 1-20 or 10-30.
      schema:
        type: string
        example: 1-20
    StatusFilter:
      name: status[]
      in: query
      required: false
      description: Filter by one or more statuses.
      schema:
        type: array
        items:
          type: string
  responses:
    BadRequest:
      description: The request was malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication. The username is your Spark Hire API key; the password is ignored. Keys are scoped to a user and respect that user's permission level.