openapi: 3.0.3
info:
  title: Spark Hire Account Users 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: Users
  description: Company users (evaluators) and their integration API keys.
paths:
  /users:
    get:
      operationId: listUsers
      tags:
      - Users
      summary: List users
      parameters:
      - $ref: '#/components/parameters/Range'
      - $ref: '#/components/parameters/OrderBy'
      responses:
        '200':
          description: A list of users.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createUser
      tags:
      - Users
      summary: Create a user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserInput'
      responses:
        '201':
          description: The created user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /users/{uuid}:
    parameters:
    - $ref: '#/components/parameters/Uuid'
    get:
      operationId: getUser
      tags:
      - Users
      summary: Get a user
      responses:
        '200':
          description: A user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateUser
      tags:
      - Users
      summary: Update a user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserInput'
      responses:
        '200':
          description: The updated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteUser
      tags:
      - Users
      summary: Delete a user
      responses:
        '204':
          description: The user was deleted.
        '404':
          $ref: '#/components/responses/NotFound'
  /users/{uuid}/integration_key:
    parameters:
    - $ref: '#/components/parameters/Uuid'
    get:
      operationId: getIntegrationKey
      tags:
      - Users
      summary: Get a user's integration API key
      responses:
        '200':
          description: The integration key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationKey'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: createIntegrationKey
      tags:
      - Users
      summary: Create a user's integration API key
      responses:
        '201':
          description: The created integration key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationKey'
    put:
      operationId: updateIntegrationKey
      tags:
      - Users
      summary: Rotate a user's integration API key
      responses:
        '200':
          description: The rotated integration key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IntegrationKey'
    delete:
      operationId: deleteIntegrationKey
      tags:
      - Users
      summary: Revoke a user's integration API key
      responses:
        '204':
          description: The integration key was revoked.
components:
  schemas:
    IntegrationKey:
      type: object
      properties:
        uuid:
          type: string
          format: uuid
        api_key:
          type: string
          description: The user's integration API key value.
        created_at:
          type: string
          format: date-time
    User:
      allOf:
      - $ref: '#/components/schemas/UserInput'
      - type: object
        properties:
          uuid:
            type: string
            format: uuid
          created_at:
            type: string
            format: date-time
          updated_at:
            type: string
            format: date-time
    UserInput:
      type: object
      properties:
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
        permission_level:
          type: string
          description: The user's role/permission level within the company.
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
  parameters:
    Uuid:
      name: uuid
      in: path
      required: true
      description: The UUID of the resource.
      schema:
        type: string
        format: uuid
    Range:
      name: range
      in: query
      required: false
      description: Pagination range, e.g. 1-20 or 10-30.
      schema:
        type: string
        example: 1-20
    OrderBy:
      name: orderby
      in: query
      required: false
      description: Sort order, e.g. title_asc or updated_desc.
      schema:
        type: string
        example: updated_desc
  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.