openapi: 3.1.0
info:
  title: Paradox Authentication Scheduling API
  description: API for the Paradox conversational AI recruiting platform powered by Olivia. Provides endpoints for managing candidates, users, interview scheduling, locations, company data, reporting, and candidate attributes. Paradox automates candidate screening, interview scheduling, and hiring workflows through chat, SMS, and mobile-driven experiences.
  version: 1.0.0
  contact:
    name: Paradox Support
    url: https://www.paradox.ai/contact
    email: support@paradox.ai
  license:
    name: Proprietary
    url: https://www.paradox.ai/legal/service-terms
  termsOfService: https://www.paradox.ai/legal/service-terms
servers:
- url: https://api.paradox.ai/api/v1/public
  description: Production (US)
- url: https://api.eu1.paradox.ai/api/v1/public
  description: Production (EU)
- url: https://stgapi.paradox.ai/api/v1/public
  description: Staging (US)
- url: https://api.stg.eu1.paradox.ai/api/v1/public
  description: Staging (EU)
- url: https://testapi.paradox.ai/api/v1/public
  description: Test
- url: https://dev2api.paradox.ai/api/v1/public
  description: Development
security:
- oauth2: []
- bearerAuth: []
tags:
- name: Scheduling
  description: Manage interview scheduling, interviewers, settings, rooms, alerts, and history
paths:
  /scheduling/multiparty-interviewers:
    get:
      operationId: getMultipartyInterviewers
      summary: Paradox Get multiparty interviewers
      description: Retrieve the list of available multiparty interviewers for scheduling.
      tags:
      - Scheduling
      responses:
        '200':
          description: Interviewers returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  interviewers:
                    type: array
                    items:
                      $ref: '#/components/schemas/Interviewer'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /scheduling/interview-settings:
    get:
      operationId: getInterviewSettings
      summary: Paradox Get interview settings
      description: Retrieve interview scheduling configuration settings.
      tags:
      - Scheduling
      responses:
        '200':
          description: Interview settings returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  settings:
                    $ref: '#/components/schemas/InterviewSettings'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /scheduling/job-location-rooms:
    get:
      operationId: getJobLocationRooms
      summary: Paradox Get job location rooms
      description: Retrieve available interview rooms for job locations.
      tags:
      - Scheduling
      responses:
        '200':
          description: Job location rooms returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  rooms:
                    type: array
                    items:
                      $ref: '#/components/schemas/Room'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /scheduling/send-interview-alerts:
    put:
      operationId: sendInterviewAlerts
      summary: Paradox Send interview alerts
      description: Send interview alert notifications to candidates and/or interviewers about upcoming or changed interviews.
      tags:
      - Scheduling
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                candidate_id:
                  type: string
                  description: Candidate identifier
                interview_id:
                  type: string
                  description: Interview identifier
                alert_type:
                  type: string
                  description: Type of alert to send
      responses:
        '200':
          description: Interview alerts sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /scheduling/interview-history:
    get:
      operationId: getInterviewHistory
      summary: Paradox Get interview history
      description: Retrieve interview history records.
      tags:
      - Scheduling
      parameters:
      - name: candidate_id
        in: query
        description: Filter by candidate identifier
        schema:
          type: string
      - name: start_date
        in: query
        description: Filter by start date
        schema:
          type: string
          format: date-time
      - name: end_date
        in: query
        description: Filter by end date
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: Interview history returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  interviews:
                    type: array
                    items:
                      $ref: '#/components/schemas/Interview'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /scheduling/communication:
    post:
      operationId: sendSchedulingCommunication
      summary: Paradox Schedule shortlist review
      description: Send an email to hiring manager(s) with a shortlist of candidates for review and scheduling.
      tags:
      - Scheduling
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - to
              - email_title
              - email_text
              - action_link
              properties:
                to:
                  type: array
                  items:
                    type: string
                  description: Hiring manager identifiers to receive the email
                email_title:
                  type: string
                  description: Email subject line
                email_text:
                  type: string
                  description: Email body content
                action_link:
                  type: string
                  format: uri
                  description: Link for the hiring manager to review candidates
      responses:
        '200':
          description: Shortlist review email sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Interviewer:
      type: object
      description: An interviewer available for multiparty scheduling
      properties:
        id:
          type: string
          description: Interviewer identifier
        name:
          type: string
          description: Interviewer name
        email:
          type: string
          format: email
          description: Interviewer email address
        timezone:
          type: string
          description: Interviewer timezone
    Room:
      type: object
      description: A room within a location used for interviews
      properties:
        oid:
          type: string
          description: Room identifier
        name:
          type: string
          description: Room name
        location_id:
          type: string
          description: Parent location identifier
        capacity:
          type: integer
          description: Room capacity
        active:
          type: boolean
          description: Whether the room is active
    InterviewSettings:
      type: object
      description: Interview scheduling configuration
      properties:
        duration:
          type: integer
          description: Default interview duration in minutes
        buffer_time:
          type: integer
          description: Buffer time between interviews in minutes
        scheduling_window:
          type: integer
          description: Number of days to look ahead for scheduling
        confirmation_required:
          type: boolean
          description: Whether interview confirmation is required
        reminder_enabled:
          type: boolean
          description: Whether interview reminders are enabled
    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
    Interview:
      type: object
      description: An interview scheduling record
      properties:
        id:
          type: string
          description: Interview identifier
        candidate_id:
          type: string
          description: Associated candidate identifier
        interviewer_id:
          type: string
          description: Assigned interviewer identifier
        location_id:
          type: string
          description: Interview location identifier
        room_id:
          type: string
          description: Interview room identifier
        scheduled_at:
          type: string
          format: date-time
          description: Scheduled interview date and time
        duration:
          type: integer
          description: Interview duration in minutes
        status:
          type: string
          description: Interview status
        type:
          type: string
          description: Interview type
        created_at:
          type: string
          format: date-time
          description: Record creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
  responses:
    Unauthorized:
      description: Authentication failed
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                const: false
              message:
                type: string
    BadRequest:
      description: Invalid request data
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                const: false
              message:
                type: string
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 client credentials authentication
      flows:
        clientCredentials:
          tokenUrl: /auth/token
          scopes: {}
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer token obtained from the OAuth 2.0 token endpoint
externalDocs:
  description: Paradox API Documentation
  url: https://readme.paradox.ai/docs