openapi: 3.1.0
info:
  title: Paradox Authentication Candidates 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: Candidates
  description: Manage candidates including creating, retrieving, updating, deleting, messaging, and unsubscribing
paths:
  /candidates:
    get:
      operationId: getCandidates
      summary: Paradox Get candidates
      description: Retrieve a list of candidates with optional filtering by date range, status, group, location, source, and other criteria.
      tags:
      - Candidates
      parameters:
      - name: start_date
        in: query
        description: Filter candidates created after this date (ISO 8601)
        schema:
          type: string
          format: date-time
      - name: end_date
        in: query
        description: Filter candidates created before this date (ISO 8601)
        schema:
          type: string
          format: date-time
      - name: created_start_date
        in: query
        description: Filter by candidate creation start date
        schema:
          type: string
          format: date-time
      - name: start_keyword
        in: query
        description: Search keyword filter
        schema:
          type: string
      - name: limit
        in: query
        description: Maximum number of results to return (max 50)
        schema:
          type: integer
          maximum: 50
          default: 50
      - name: offset
        in: query
        description: Number of results to skip for pagination
        schema:
          type: integer
          default: 0
      - name: page
        in: query
        description: Page number for pagination
        schema:
          type: integer
      - name: status
        in: query
        description: Filter by candidate status
        schema:
          type: string
      - name: group_name
        in: query
        description: Filter by group name
        schema:
          type: string
      - name: location_id
        in: query
        description: Filter by location identifier
        schema:
          type: string
      - name: source
        in: query
        description: Filter by candidate source
        schema:
          type: string
      - name: conversation
        in: query
        description: Include conversation data
        schema:
          type: boolean
      - name: interviews
        in: query
        description: Include interview data
        schema:
          type: boolean
      - name: note
        in: query
        description: Include candidate notes
        schema:
          type: boolean
      - name: profile_id
        in: query
        description: Filter by profile identifier
        schema:
          type: string
      - name: include_attributes
        in: query
        description: Include candidate attribute data in response
        schema:
          type: boolean
      - name: candidate_journey_status
        in: query
        description: Filter by candidate journey status
        schema:
          type: string
      - name: job_loc_code
        in: query
        description: Filter by job location code
        schema:
          type: string
      - name: job_req_id
        in: query
        description: Filter by job requisition ID
        schema:
          type: string
      - name: ex_id
        in: query
        description: Filter by external candidate identifier
        schema:
          type: string
      - name: email
        in: query
        description: Filter by candidate email
        schema:
          type: string
          format: email
      responses:
        '200':
          description: List of candidates returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  candidates:
                    type: array
                    items:
                      $ref: '#/components/schemas/Candidate'
                  limit:
                    type: integer
                  count:
                    type: integer
                  offset:
                    type: integer
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createCandidate
      summary: Paradox Create candidate
      description: Create a new candidate in the Paradox platform. Requires at minimum a name (or first_name and last_name), phone number, and email address.
      tags:
      - Candidates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CandidateCreate'
          multipart/form-data:
            schema:
              allOf:
              - $ref: '#/components/schemas/CandidateCreate'
              - type: object
                properties:
                  resume:
                    type: string
                    format: binary
                    description: Resume file (PDF, DOC, DOCX, PNG, JPG, TXT; max 10MB)
                  offer_letter:
                    type: string
                    format: binary
                    description: Offer letter file (DOC, DOCX, PDF, PNG, JPG, JPEG, TXT, Pages, HTML; max 10MB)
                  candidatedata:
                    type: string
                    format: binary
                    description: Bulk operation file for mass create/update
      responses:
        '200':
          description: Candidate created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  candidate:
                    $ref: '#/components/schemas/Candidate'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /candidates/{id}:
    get:
      operationId: getCandidate
      summary: Paradox Get single candidate
      description: Retrieve details for a specific candidate by OID or external OID.
      tags:
      - Candidates
      parameters:
      - $ref: '#/components/parameters/CandidateId'
      - name: conversation
        in: query
        description: Include conversation history
        schema:
          type: boolean
      - name: note
        in: query
        description: Include candidate notes
        schema:
          type: boolean
      responses:
        '200':
          description: Candidate details returned successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  candidate:
                    $ref: '#/components/schemas/Candidate'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateCandidate
      summary: Paradox Update candidate
      description: Update an existing candidate by OID, external OID, or external ID. Supports updating name, contact information, status, journey details, attributes, and attached documents.
      tags:
      - Candidates
      parameters:
      - $ref: '#/components/parameters/CandidateId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CandidateUpdate'
          multipart/form-data:
            schema:
              allOf:
              - $ref: '#/components/schemas/CandidateUpdate'
              - type: object
                properties:
                  resume:
                    type: string
                    format: binary
                    description: Resume file (max 10MB)
                  offer_letter:
                    type: string
                    format: binary
                    description: Offer letter file (max 10MB)
      responses:
        '200':
          description: Candidate updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  candidate:
                    $ref: '#/components/schemas/Candidate'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteCandidate
      summary: Paradox Delete candidate
      description: Delete a candidate by OID or external OID.
      tags:
      - Candidates
      parameters:
      - $ref: '#/components/parameters/CandidateId'
      responses:
        '200':
          description: Candidate deleted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /candidates/unsubscribe:
    put:
      operationId: unsubscribeCandidate
      summary: Paradox Unsubscribe candidate
      description: Unsubscribe or resubscribe a candidate from communications. Use action_id 1 to unsubscribe and 0 to resubscribe.
      tags:
      - Candidates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - OID
              - action_id
              properties:
                OID:
                  type: integer
                  description: Candidate internal identifier
                action_id:
                  type: integer
                  enum:
                  - 0
                  - 1
                  description: 1 to unsubscribe, 0 to resubscribe
      responses:
        '200':
          description: Subscription status updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  OID:
                    type: integer
                  unsubscribed:
                    type: boolean
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /candidates/send_message:
    post:
      operationId: sendCandidateMessage
      summary: Paradox Send candidate message
      description: Send a message to a candidate via their preferred contact method.
      tags:
      - Candidates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - OID
              - message
              properties:
                OID:
                  type: integer
                  description: Candidate internal identifier
                message:
                  type: string
                  description: Message content to send
                send_as:
                  type: string
                  description: Send message as a specific user
                contact_method:
                  type: string
                  description: Contact method to use for delivery
                email_subject:
                  type: string
                  description: Email subject line (when sending via email)
      responses:
        '200':
          description: Message sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /candidates/background_check/standard:
    post:
      operationId: sendBackgroundCheckStandard
      summary: Paradox Send standard background check
      description: Initiate a standard background check for a candidate.
      tags:
      - Candidates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                candidate_id:
                  type: string
                  description: Paradox candidate identifier
                ex_application_id:
                  type: string
                  description: External application identifier
                ex_candidate_id:
                  type: string
                  description: External candidate identifier
                background_check_url:
                  type: string
                  format: uri
                  description: URL for the background check
                status:
                  type: string
                  description: Background check status
      responses:
        '200':
          description: Background check initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /candidates/background_check/checkr:
    post:
      operationId: sendBackgroundCheckCheckr
      summary: Paradox Send Checkr background check
      description: Initiate a background check through Checkr integration.
      tags:
      - Candidates
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                candidate_id:
                  type: string
                  description: Paradox candidate identifier
                status:
                  type: string
                  description: Background check status
      responses:
        '200':
          description: Checkr background check initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /candidates/background_check/firstadvance:
    post:
      operationId: sendBackgroundCheckFirstAdvantage
      summary: Paradox Send First Advantage background check
      description: Initiate a background check through First Advantage integration.
      tags:
      - Candidates
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  format: uri
                  description: First Advantage check URL
                status:
                  type: string
                  description: Background check status
                sf_applicant_id:
                  type: string
                  description: Salesforce applicant identifier
      responses:
        '200':
          description: First Advantage background check initiated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    CandidateUpdate:
      type: object
      description: Request body for updating an existing candidate
      properties:
        name:
          type: string
          maxLength: 50
        first_name:
          type: string
        last_name:
          type: string
        phone:
          type: string
          maxLength: 20
        email:
          type: string
          format: email
          maxLength: 50
        ex_id:
          type: string
          maxLength: 255
        hirevue_link:
          type: string
          maxLength: 255
        pymetrics_link:
          type: string
          maxLength: 255
        ex_step:
          type: string
        ex_status:
          type: string
        ex_reason:
          type: string
        job_req_id:
          type: string
          maxLength: 255
        job_title:
          type: string
          maxLength: 255
        job_loc_code:
          type: string
          maxLength: 20
        primary_contact_method:
          type: string
        hired_date:
          type: string
          format: date-time
        adp_link:
          type: string
          maxLength: 255
        audience_type:
          type: string
          maxLength: 255
        recruiter_email:
          type: string
          format: email
        hiring_manager:
          type: string
        language_preference:
          type: string
        candidate_journey:
          type: string
        candidate_journey_status:
          type: string
        candidate_attribute_data:
          type: object
          additionalProperties:
            type: string
            maxLength: 255
        note:
          type: string
        use_paradox_status_map:
          type: boolean
        status_map_name:
          type: string
        status_map_ex_id:
          type: string
    Candidate:
      type: object
      description: A candidate in the Paradox recruiting platform
      properties:
        OID:
          type: integer
          description: Unique internal candidate identifier
        external_oid:
          type: string
          description: Encrypted external candidate identifier
        name:
          type: string
          maxLength: 50
          description: Full name of the candidate
        first_name:
          type: string
          description: First name of the candidate
        last_name:
          type: string
          description: Last name of the candidate
        email:
          type: string
          format: email
          maxLength: 50
          description: Email address
        phone:
          type: string
          maxLength: 20
          description: Phone number with country code
        ex_id:
          type: string
          maxLength: 255
          description: External candidate identifier
        ex_status:
          type: string
          description: External status designation
        ex_step:
          type: string
          description: External step designation
        ex_reason:
          type: string
          description: External reason designation
        job_req_id:
          type: string
          maxLength: 255
          description: Job requisition identifier
        job_title:
          type: string
          maxLength: 255
          description: Job position title
        job_loc_code:
          type: string
          maxLength: 20
          description: Job location code
        primary_contact_method:
          type: integer
          enum:
          - 1
          - 2
          - 3
          - 4
          - 5
          description: 'Contact preference: 1=Email, 2=SMS, 3=Email & SMS, 4=WhatsApp & Email, 5=WhatsApp'
        hired_date:
          type:
          - string
          - 'null'
          format: date-time
          description: Employment start date
        hirevue_link:
          type: string
          maxLength: 255
          description: HireVue virtual interview link
        pymetrics_link:
          type: string
          maxLength: 255
          description: Pymetrics assessment link
        adp_link:
          type: string
          maxLength: 255
          description: ADP system link
        hirevue_instructions:
          type: string
          maxLength: 255
          description: Interview guidance text
        audience_type:
          type: string
          maxLength: 255
          description: Candidate tier classification
        hm_cid:
          type: string
          maxLength: 255
          description: Hirescore candidate identifier
        external_group_id:
          type: string
          description: Group classification identifier
        referrer_email:
          type: string
          format: email
          maxLength: 50
          description: Referral source email address
        referrer_name:
          type: string
          maxLength: 50
          description: Referral source name
        recruiter_email:
          type: string
          format: email
          description: Assigned recruiter email
        hiring_manager:
          type: string
          description: Assigned hiring manager contact
        external_referrer:
          type: string
          maxLength: 1000
          description: External referral source
        language_preference:
          type: string
          default: en
          description: Language code preference
        candidate_journey:
          type: string
          description: Journey workflow name
        candidate_journey_status:
          type: string
          description: Current journey stage designation
        candidate_attribute_data:
          type: object
          additionalProperties:
            type: string
            maxLength: 255
          description: Custom key-value attributes
        job_application_id:
          type: string
          maxLength: 255
          description: Application identifier
        candidate_location_info:
          type: string
          maxLength: 100
          description: Geographic location information
        external_source_id:
          type: string
          maxLength: 255
          description: Source system identifier
        talent_community:
          type: boolean
          default: false
          description: Whether candidate is in the talent pool
        community_of_interest:
          type: integer
          description: Community identifier when in talent pool
        consent_to_marketing:
          type: string
          description: Marketing consent status
        note:
          type: string
          description: Internal candidate notes
    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
    CandidateCreate:
      type: object
      description: Request body for creating a new candidate
      required:
      - phone
      - email
      properties:
        name:
          type: string
          maxLength: 50
          description: Full name (required if first_name/last_name not provided)
        first_name:
          type: string
          description: First name (use with last_name instead of name)
        last_name:
          type: string
          description: Last name (use with first_name instead of name)
        phone:
          type: string
          maxLength: 20
          description: Phone number with country code
        email:
          type: string
          format: email
          maxLength: 50
          description: Email address
        ex_id:
          type: string
          maxLength: 255
          description: External candidate identifier
        hirevue_link:
          type: string
          maxLength: 255
        pymetrics_link:
          type: string
          maxLength: 255
        ex_step:
          type: string
        ex_status:
          type: string
        ex_reason:
          type: string
        job_req_id:
          type: string
          maxLength: 255
        job_title:
          type: string
          maxLength: 255
        job_loc_code:
          type: string
          maxLength: 20
        primary_contact_method:
          type: string
          description: 1=Email, 2=SMS, 3=Email & SMS, 4=WhatsApp & Email, 5=WhatsApp
        hired_date:
          type: string
          format: date-time
        adp_link:
          type: string
          maxLength: 255
        audience_type:
          type: string
          maxLength: 255
        hm_cid:
          type: string
          maxLength: 255
        external_group_id:
          type: string
        hirevue_instructions:
          type: string
          maxLength: 255
        referrer_email:
          type: string
          format: email
          maxLength: 50
        referrer_name:
          type: string
          maxLength: 50
        recruiter_email:
          type: string
          format: email
        hiring_manager:
          type: string
        external_referrer:
          type: string
          maxLength: 1000
        language_preference:
          type: string
          default: en
        candidate_journey:
          type: string
        candidate_journey_status:
          type: string
        candidate_attribute_data:
          type: object
          additionalProperties:
            type: string
            maxLength: 255
        note:
          type: string
        job_application_id:
          type: string
          maxLength: 255
        use_application_id_for_identity:
          type: boolean
          default: false
          description: Use application ID to identify returning candidates
        candidate_location_info:
          type: string
          maxLength: 100
        external_source_id:
          type: string
          maxLength: 255
        offer_file_name:
          type: string
          maxLength: 150
          description: Offer document filename
        use_paradox_status_map:
          type: boolean
          default: false
          description: Enable Paradox status mapping
        status_map_name:
          type: string
          description: Paradox journey status name for mapping
        status_map_ex_id:
          type: string
          description: External system status identifier for mapping
        talent_community:
          type: boolean
          default: false
        community_of_interest:
          type: integer
        skip_send_opt_in:
          type: boolean
          description: Bypass opt-in messaging
        consent_to_marketing:
          type: string
  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
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                const: false
              message:
                type: string
  parameters:
    CandidateId:
      name: id
      in: path
      required: true
      description: Candidate OID, external OID, or external ID
      schema:
        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