openapi: 3.0.3
info:
  title: Trakstar Hire Auth Candidates API
  description: The Trakstar Hire REST API (formerly Recruiterbox) enables developers to manage openings, candidates, candidate messages, internal notes, interviews, reviews, evaluations, and to-dos programmatically. It returns JSON responses and uses API key authentication generated from the account's Super Admin settings. The most common use cases include building custom career sites and syncing opening or candidate data with external systems.
  version: '2'
  contact:
    name: Trakstar Hire Support
    url: https://support.hire.trakstar.com/article/1617-accessing-the-hire-api
  license:
    name: Proprietary
servers:
- url: https://{companyName}.hire.trakstar.com/api/v2
  description: Trakstar Hire API v2
  variables:
    companyName:
      description: Your company subdomain name
      default: yourcompany
security:
- apiKey: []
tags:
- name: Candidates
  description: Manage job candidates
paths:
  /candidates:
    get:
      operationId: listCandidates
      summary: List Candidates
      description: Returns a paginated list of candidates, optionally filtered by opening.
      tags:
      - Candidates
      parameters:
      - name: opening
        in: query
        description: Filter candidates by opening ID.
        required: false
        schema:
          type: integer
      - name: limit
        in: query
        description: Number of results per page.
        required: false
        schema:
          type: integer
          default: 10
          maximum: 100
      - name: offset
        in: query
        description: Number of results to skip for pagination.
        required: false
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: A list of candidates.
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                  next:
                    type: string
                    nullable: true
                  previous:
                    type: string
                    nullable: true
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Candidate'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createCandidate
      summary: Create Candidate
      description: Creates a new candidate record.
      tags:
      - Candidates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CandidateInput'
      responses:
        '201':
          description: Candidate created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Candidate'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /candidates/{id}:
    get:
      operationId: getCandidate
      summary: Get Candidate
      description: Returns a single candidate by ID.
      tags:
      - Candidates
      parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of the candidate.
        schema:
          type: integer
      responses:
        '200':
          description: A single candidate.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Candidate'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateCandidate
      summary: Update Candidate
      description: Partially updates a candidate record.
      tags:
      - Candidates
      parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of the candidate.
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CandidateInput'
      responses:
        '200':
          description: Candidate updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Candidate'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteCandidate
      summary: Delete Candidate
      description: Deletes a candidate record.
      tags:
      - Candidates
      parameters:
      - name: id
        in: path
        required: true
        description: The unique identifier of the candidate.
        schema:
          type: integer
      responses:
        '204':
          description: Candidate deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    Unauthorized:
      description: Authentication credentials were not provided or are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource could not be found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request was invalid or cannot be otherwise served.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    CandidateInput:
      type: object
      required:
      - first_name
      - last_name
      - opening
      properties:
        first_name:
          type: string
          description: Candidate's first name.
        last_name:
          type: string
          description: Candidate's last name.
        email:
          type: string
          format: email
          description: Candidate's email address.
        phone:
          type: string
          description: Candidate's phone number.
          nullable: true
        opening:
          type: integer
          description: ID of the opening the candidate is applying to.
        source:
          type: string
          description: Source of the candidate application.
          nullable: true
    Error:
      type: object
      properties:
        detail:
          type: string
          description: Human-readable error message.
    Candidate:
      type: object
      description: A candidate applying to a job opening.
      properties:
        id:
          type: integer
          description: Unique identifier for the candidate.
          readOnly: true
        first_name:
          type: string
          description: Candidate's first name.
        last_name:
          type: string
          description: Candidate's last name.
        email:
          type: string
          format: email
          description: Candidate's email address.
        phone:
          type: string
          description: Candidate's phone number.
          nullable: true
        opening:
          type: integer
          description: ID of the opening the candidate is applying to.
        stage:
          type: string
          description: Current stage of the candidate in the hiring pipeline.
          nullable: true
        source:
          type: string
          description: Source of the candidate application.
          nullable: true
        created_at:
          type: string
          format: date-time
          description: Timestamp when the candidate record was created.
          readOnly: true
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the candidate record was last updated.
          readOnly: true
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: API key generated from the Trakstar Hire Super Admin settings page. Pass as "ApiKey {your_api_key}".
externalDocs:
  description: Trakstar Hire API Reference
  url: https://developers.recruiterbox.com/reference/introduction