Paradox Candidate Attributes API
API for managing candidate attributes within the Paradox platform including retrieving, patching, and updating candidate attribute data.
OpenAPI Specification
openapi: 3.1.0
info:
title: Paradox 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: [email protected]
license:
name: Proprietary
url: https://www.paradox.ai/legal/service-terms
termsOfService: https://www.paradox.ai/legal/service-terms
externalDocs:
description: Paradox API Documentation
url: https://readme.paradox.ai/docs
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: Authentication
description: OAuth 2.0 token and JWT verification endpoints
- name: Candidate Attributes
description: Manage custom candidate attribute data
- name: Candidates
description: Manage candidates including creating, retrieving, updating, deleting, messaging, and unsubscribing
- name: Company
description: Access company-level data including conversations, groups, schools, areas, and AI assistant
- name: Location Areas
description: Manage location areas
- name: Location Rooms
description: Manage location rooms
- name: Locations
description: Manage locations including creating, retrieving, updating, deleting, and lookup by job location code
- name: Reporting
description: Access and generate reports
- name: Scheduling
description: Manage interview scheduling, interviewers, settings, rooms, alerts, and history
- name: User Permissions
description: Manage user location permissions
- name: Users
description: Manage users including creating, retrieving, updating, deleting, deactivating, and reactivating
paths:
# ── Authentication ──────────────────────────────────────────────────
/auth/token:
post:
operationId: getAuthToken
summary: Paradox Get OAuth 2.0 access token
description: >-
Obtain an access token using OAuth 2.0 client credentials grant.
The returned token should be included in the Authorization header
as a Bearer token for subsequent API requests.
tags:
- Authentication
security: []
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- client_id
- client_secret
- grant_type
properties:
client_id:
type: string
description: Account ID provided by Paradox
client_secret:
type: string
description: Secret key provided by Paradox
grant_type:
type: string
enum:
- client_credentials
description: OAuth 2.0 grant type
responses:
'200':
description: Access token issued successfully
content:
application/json:
schema:
type: object
properties:
access_token:
type: string
description: Bearer access token
expires_in:
type: integer
description: Token expiration time in seconds
token_type:
type: string
description: Token type (Bearer)
'401':
$ref: '#/components/responses/Unauthorized'
/verify-jwt:
post:
operationId: verifyJwt
summary: Paradox Verify JWT token
description: Verify the validity of a JWT authentication token.
tags:
- Authentication
responses:
'200':
description: Token is valid
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'432':
description: Token expired
# ── Candidates ──────────────────────────────────────────────────────
/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'
# ── Candidate Attributes ────────────────────────────────────────────
/candidate/attributes/{oid}:
get:
operationId: getCandidateAttributes
summary: Paradox Get candidate attributes
description: Retrieve all current custom attributes for a specific candidate.
tags:
- Candidate Attributes
parameters:
- name: oid
in: path
required: true
description: Candidate OID or external OID
schema:
type: string
responses:
'200':
description: Candidate attributes returned successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
attributes:
type: object
additionalProperties:
type: string
maxLength: 255
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/candidate/attributes:
patch:
operationId: patchCandidateAttributes
summary: Paradox Patch candidate attributes
description: >-
Partially update candidate attributes. Only the specified attributes
will be modified; existing attributes not included will remain unchanged.
tags:
- Candidate Attributes
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- oid
- attributes
properties:
oid:
type: string
description: Candidate OID or external OID
attributes:
type: object
additionalProperties:
type: string
maxLength: 255
description: Key-value pairs of attributes to update
responses:
'200':
description: Candidate attributes patched successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
put:
operationId: updateCandidateAttributes
summary: Paradox Update candidate attributes
description: >-
Replace all candidate attributes with the provided set. Any attributes
not included in the request will be removed.
tags:
- Candidate Attributes
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- oid
- attributes
properties:
oid:
type: string
description: Candidate OID or external OID
attributes:
type: object
additionalProperties:
type: string
maxLength: 255
description: Complete set of key-value attribute pairs
responses:
'200':
description: Candidate attributes updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
# ── Users ───────────────────────────────────────────────────────────
/users:
get:
operationId: getUsers
summary: Paradox Get users
description: Retrieve a paginated list of users in the Paradox platform.
tags:
- Users
parameters:
- name: limit
in: query
description: Maximum number of results to return
schema:
type: integer
- name: page
in: query
description: Page number for pagination
schema:
type: integer
- name: include_campus_permission
in: query
description: Include campus permission data in response
schema:
type: boolean
- name: external_role_id
in: query
description: Filter by external role identifier
schema:
type: string
- name: location_id
in: query
description: Filter by location identifier
schema:
type: string
responses:
'200':
description: List of users returned successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
users:
type: array
items:
$ref: '#/components/schemas/User'
limit:
type: integer
count:
type: integer
page:
type: integer
'401':
$ref: '#/components/responses/Unauthorized'
post:
operationId: createUser
summary: Paradox Create user
description: Create a new user in the Paradox platform.
tags:
- Users
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserCreate'
responses:
'200':
description: User created successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
user:
$ref: '#/components/schemas/User'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
/users/{oid}:
get:
operationId: getUser
summary: Paradox Get single user
description: Retrieve details for a specific user by OID or external identifier.
tags:
- Users
parameters:
- $ref: '#/components/parameters/UserOid'
responses:
'200':
description: User details returned successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
user:
$ref: '#/components/schemas/User'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: updateUser
summary: Paradox Update user
description: Update an existing user by OID.
tags:
- Users
parameters:
- $ref: '#/components/parameters/UserOid'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UserUpdate'
responses:
'200':
description: User updated successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
user:
$ref: '#/components/schemas/User'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteUser
summary: Paradox Delete user
description: Delete a user by OID.
tags:
- Users
parameters:
- $ref: '#/components/parameters/UserOid'
responses:
'200':
description: User deleted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/users/{oid}/deactivate:
post:
operationId: deactivateUser
summary: Paradox Deactivate user
description: Deactivate a user account, preventing login and API access.
tags:
- Users
parameters:
- $ref: '#/components/parameters/UserOid'
responses:
'200':
description: User deactivated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/users/{oid}/reactivate:
post:
operationId: reactivateUser
summary: Paradox Reactivate user
description: Reactivate a previously deactivated user account.
tags:
- Users
parameters:
- $ref: '#/components/parameters/UserOid'
responses:
'200':
description: User reactivated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
/users/roles:
get:
operationId: getUserRoles
summary: Paradox Get user roles
description: Retrieve the list of available user roles.
tags:
- Users
responses:
'200':
description: User roles returned successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
roles:
type: array
items:
$ref: '#/components/schemas/Role'
'401':
$ref: '#/components/responses/Unauthorized'
/users/employees/{employee_id}:
get:
operationId: getUserByEmployeeId
summary: Paradox Get user by employee ID
description: Look up a user by their employee ID.
tags:
- Users
parameters:
- name: employee_id
in: path
required: true
description: Employee identifier
schema:
type: string
responses:
'200':
description: User details returned successfully
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
user:
$ref: '#/components/schemas/User'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: updateUserByEmployeeId
summary: Paradox Update user by employee ID
description: Update a user identified by their employee ID.
tags:
- Users
parameters:
- name: employee_id
in: path
required: true
description: Employee identifier
schema:
type: string
requestBody:
# --- truncated at 32 KB (89 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/paradox/refs/heads/main/openapi/paradox-api-openapi.yml