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