{
  "$id": "paradox-candidate-schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Paradox Candidate",
  "description": "JSON Schema for a candidate resource in the Paradox conversational AI recruiting platform. Candidates represent individuals progressing through automated screening, interview scheduling, and hiring workflows powered by the Olivia AI assistant.",
  "type": "object",
  "required": [
    "phone",
    "email"
  ],
  "properties": {
    "OID": {
      "type": "integer",
      "description": "Unique internal candidate identifier assigned by Paradox"
    },
    "external_oid": {
      "type": "string",
      "description": "Encrypted external candidate identifier"
    },
    "name": {
      "type": "string",
      "maxLength": 50,
      "description": "Full name of the candidate (required if first_name/last_name not provided)"
    },
    "first_name": {
      "type": "string",
      "description": "First name of the candidate (use with last_name instead of name)"
    },
    "last_name": {
      "type": "string",
      "description": "Last name of the candidate (use with first_name instead of name)"
    },
    "email": {
      "type": "string",
      "format": "email",
      "maxLength": 50,
      "description": "Candidate email address"
    },
    "phone": {
      "type": "string",
      "maxLength": 20,
      "description": "Candidate phone number with country code"
    },
    "ex_id": {
      "type": "string",
      "maxLength": 255,
      "description": "External candidate identifier from an integrated system"
    },
    "ex_status": {
      "type": "string",
      "description": "External status designation from an integrated system"
    },
    "ex_step": {
      "type": "string",
      "description": "External step designation from an integrated system"
    },
    "ex_reason": {
      "type": "string",
      "description": "External reason designation from an integrated system"
    },
    "job_req_id": {
      "type": "string",
      "maxLength": 255,
      "description": "Job requisition identifier the candidate is associated with"
    },
    "job_title": {
      "type": "string",
      "maxLength": 255,
      "description": "Job position title the candidate is applying for"
    },
    "job_loc_code": {
      "type": "string",
      "maxLength": 20,
      "description": "Job location code identifying the candidate work site"
    },
    "primary_contact_method": {
      "type": "integer",
      "enum": [1, 2, 3, 4, 5],
      "description": "Preferred contact method: 1=Email, 2=SMS, 3=Email & SMS, 4=WhatsApp & Email, 5=WhatsApp"
    },
    "hired_date": {
      "type": ["string", "null"],
      "format": "date-time",
      "description": "Employment start date (ISO 8601 format)"
    },
    "hirevue_link": {
      "type": "string",
      "maxLength": 255,
      "format": "uri",
      "description": "HireVue virtual interview link"
    },
    "pymetrics_link": {
      "type": "string",
      "maxLength": 255,
      "format": "uri",
      "description": "Pymetrics assessment platform link"
    },
    "adp_link": {
      "type": "string",
      "maxLength": 255,
      "format": "uri",
      "description": "ADP workforce management system link"
    },
    "hirevue_instructions": {
      "type": "string",
      "maxLength": 255,
      "description": "Interview guidance text provided to the candidate"
    },
    "audience_type": {
      "type": "string",
      "maxLength": 255,
      "description": "Candidate tier classification for segmentation"
    },
    "hm_cid": {
      "type": "string",
      "maxLength": 255,
      "description": "Hirescore candidate identifier"
    },
    "external_group_id": {
      "type": "string",
      "description": "Group classification identifier for organizing candidates"
    },
    "referrer_email": {
      "type": "string",
      "format": "email",
      "maxLength": 50,
      "description": "Email address of the person who referred the candidate"
    },
    "referrer_name": {
      "type": "string",
      "maxLength": 50,
      "description": "Name of the person who referred the candidate"
    },
    "recruiter_email": {
      "type": "string",
      "format": "email",
      "description": "Email of the assigned recruiter"
    },
    "hiring_manager": {
      "type": "string",
      "description": "Contact information for the assigned hiring manager"
    },
    "external_referrer": {
      "type": "string",
      "maxLength": 1000,
      "description": "External referral source information"
    },
    "language_preference": {
      "type": "string",
      "default": "en",
      "description": "Candidate language preference code (e.g. en, es, fr)"
    },
    "candidate_journey": {
      "type": "string",
      "description": "Name of the journey workflow the candidate is enrolled in"
    },
    "candidate_journey_status": {
      "type": "string",
      "description": "Current stage designation within the candidate journey"
    },
    "candidate_attribute_data": {
      "type": "object",
      "additionalProperties": {
        "type": "string",
        "maxLength": 255
      },
      "description": "Custom candidate attributes as key-value pairs (values limited to 255 characters each)"
    },
    "job_application_id": {
      "type": "string",
      "maxLength": 255,
      "description": "Application identifier for the candidate"
    },
    "use_application_id_for_identity": {
      "type": "boolean",
      "default": false,
      "description": "Whether to use the application ID to identify returning candidates"
    },
    "candidate_location_info": {
      "type": "string",
      "maxLength": 100,
      "description": "Geographic location information for the candidate"
    },
    "external_source_id": {
      "type": "string",
      "maxLength": 255,
      "description": "Source system identifier indicating where the candidate originated"
    },
    "offer_file_name": {
      "type": "string",
      "maxLength": 150,
      "description": "Filename of the attached offer letter document"
    },
    "use_paradox_status_map": {
      "type": "boolean",
      "default": false,
      "description": "Whether to enable Paradox status mapping"
    },
    "status_map_name": {
      "type": "string",
      "description": "Paradox journey status name for status mapping"
    },
    "status_map_ex_id": {
      "type": "string",
      "description": "External system status identifier for status mapping"
    },
    "talent_community": {
      "type": "boolean",
      "default": false,
      "description": "Whether the candidate is added to the talent pool"
    },
    "community_of_interest": {
      "type": "integer",
      "description": "Community identifier when talent_community is true"
    },
    "skip_send_opt_in": {
      "type": "boolean",
      "description": "Whether to bypass opt-in messaging"
    },
    "consent_to_marketing": {
      "type": "string",
      "description": "Marketing consent status for the candidate"
    },
    "note": {
      "type": "string",
      "description": "Internal notes about the candidate"
    }
  },
  "oneOf": [
    {
      "required": ["name"]
    },
    {
      "required": ["first_name", "last_name"]
    }
  ],
  "examples": [
    {
      "name": "Jane Smith",
      "email": "jane.smith@example.com",
      "phone": "+15551234567",
      "job_req_id": "REQ-2026-001",
      "job_title": "Software Engineer",
      "job_loc_code": "US-NY-100",
      "primary_contact_method": 3,
      "language_preference": "en",
      "candidate_journey": "Standard Hiring",
      "candidate_attribute_data": {
        "years_experience": "5",
        "degree": "BS Computer Science"
      }
    }
  ]
}