{
  "components": {
    "schemas": {
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "title": "Detail",
            "type": "array"
          }
        },
        "title": "HTTPValidationError",
        "type": "object"
      },
      "PartnerAuthValidateResponse": {
        "properties": {
          "env": {
            "title": "Env",
            "type": "string"
          },
          "exp": {
            "title": "Exp",
            "type": "integer"
          },
          "jti": {
            "title": "Jti",
            "type": "string"
          },
          "partner_id": {
            "title": "Partner Id",
            "type": "string"
          },
          "partner_uuid": {
            "title": "Partner Uuid",
            "type": "string"
          },
          "scopes": {
            "items": {
              "type": "string"
            },
            "title": "Scopes",
            "type": "array"
          },
          "sub": {
            "title": "Sub",
            "type": "string"
          }
        },
        "required": [
          "sub",
          "partner_id",
          "partner_uuid",
          "scopes",
          "env",
          "jti",
          "exp"
        ],
        "title": "PartnerAuthValidateResponse",
        "type": "object"
      },
      "PartnerCandidateProfile": {
        "examples": [
          {
            "application_id": "app_uuid",
            "applied_at": "2026-06-01T10:00:00Z",
            "candidate_id": "AIV-CAND-55661",
            "current_location": "Pune",
            "email": "priya@example.com",
            "employer_status": "shortlisted",
            "job_id": "AIV-JOB-77881",
            "mobile": "9876543210",
            "name": "Priya Sharma",
            "screening_status": "completed",
            "skills": [
              "picking",
              "packing"
            ]
          }
        ],
        "properties": {
          "application_id": {
            "title": "Application Id",
            "type": "string"
          },
          "applied_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Applied At"
          },
          "candidate_id": {
            "title": "Candidate Id",
            "type": "string"
          },
          "current_location": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Current Location"
          },
          "email": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Candidate email; null if not provided",
            "title": "Email"
          },
          "employer_status": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Employer Status"
          },
          "job_id": {
            "title": "Job Id",
            "type": "string"
          },
          "mobile": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Candidate mobile (login identity)",
            "title": "Mobile"
          },
          "name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Name"
          },
          "partner_stage": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Partner Stage"
          },
          "screening_status": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Screening Status"
          },
          "skills": {
            "items": {
              "type": "string"
            },
            "title": "Skills",
            "type": "array"
          }
        },
        "required": [
          "candidate_id",
          "application_id",
          "job_id"
        ],
        "title": "PartnerCandidateProfile",
        "type": "object"
      },
      "PartnerCandidateProfileResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/PartnerCandidateProfile"
          },
          "error": {
            "anyOf": [
              {},
              {
                "type": "null"
              }
            ],
            "title": "Error"
          },
          "meta": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Meta"
          },
          "success": {
            "default": true,
            "title": "Success",
            "type": "boolean"
          }
        },
        "required": [
          "data"
        ],
        "title": "PartnerCandidateProfileResponse",
        "type": "object"
      },
      "PartnerCandidateResumeData": {
        "properties": {
          "application_id": {
            "title": "Application Id",
            "type": "string"
          },
          "candidate_id": {
            "title": "Candidate Id",
            "type": "string"
          },
          "expires_in": {
            "description": "Signed URL lifetime in seconds",
            "examples": [
              600
            ],
            "title": "Expires In",
            "type": "integer"
          },
          "file_kind": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "image | document",
            "title": "File Kind"
          },
          "file_name": {
            "examples": [
              "Priya_Sharma.pdf",
              "cv.jpg"
            ],
            "title": "File Name",
            "type": "string"
          },
          "job_id": {
            "title": "Job Id",
            "type": "string"
          },
          "mime_type": {
            "examples": [
              "application/pdf",
              "image/jpeg"
            ],
            "title": "Mime Type",
            "type": "string"
          },
          "resume_url": {
            "description": "Time-limited HTTPS GET URL. Do not persist; refetch when expired.",
            "examples": [
              "https://xyz.supabase.co/storage/v1/object/sign/resumes/cand/cv.pdf?token=..."
            ],
            "title": "Resume Url",
            "type": "string"
          }
        },
        "required": [
          "candidate_id",
          "application_id",
          "job_id",
          "resume_url",
          "expires_in",
          "mime_type",
          "file_name"
        ],
        "title": "PartnerCandidateResumeData",
        "type": "object"
      },
      "PartnerCandidateResumeResponse": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/PartnerCandidateResumeData"
          },
          "error": {
            "anyOf": [
              {},
              {
                "type": "null"
              }
            ],
            "title": "Error"
          },
          "meta": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Meta"
          },
          "success": {
            "default": true,
            "title": "Success",
            "type": "boolean"
          }
        },
        "required": [
          "data"
        ],
        "title": "PartnerCandidateResumeResponse",
        "type": "object"
      },
      "PartnerJobCreateRequest": {
        "properties": {
          "ad_generation_language": {
            "anyOf": [
              {
                "maxLength": 64,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "deprecated": true,
            "description": "[Deprecated] Ignored by platform. Poster and ad locales are determined by the platform.",
            "title": "Ad Generation Language"
          },
          "callback_urls": {
            "anyOf": [
              {
                "additionalProperties": {
                  "type": "string"
                },
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional per-job webhook URL overrides. Keys: creative_ready, candidate_update, grading_update, analytics_update. Values must be http(s) URLs.",
            "title": "Callback Urls"
          },
          "description": {
            "anyOf": [
              {
                "maxLength": 50000,
                "minLength": 10,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Full JD text. Required unless jd_url is provided. Minimum 10 characters after trim (max 50000). Plain text with \\n for line breaks, or HTML using only: p, br, div, span, b, strong, em, i, u, h1-h6, ul, ol, li, blockquote, hr, table/thead/tbody/tr/th/td. No script/style/anchor tags or attributes; other tags are rejected with a 422.",
            "title": "Description"
          },
          "education": {
            "anyOf": [
              {
                "maxLength": 500,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Education requirement (max 500)",
            "title": "Education"
          },
          "employment_type": {
            "anyOf": [
              {
                "maxLength": 64,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Free text employment type (max 64), e.g. Permanent, full_time",
            "title": "Employment Type"
          },
          "experience": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/PartnerJobExperience"
              },
              {
                "type": "null"
              }
            ]
          },
          "external_client_id": {
            "anyOf": [
              {
                "maxLength": 128,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional end-customer / client reference",
            "title": "External Client Id"
          },
          "external_job_id": {
            "description": "Your stable job id (1-128). Idempotent per partner+tenant.",
            "maxLength": 128,
            "minLength": 1,
            "title": "External Job Id",
            "type": "string"
          },
          "jd_url": {
            "anyOf": [
              {
                "maxLength": 2000,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional JD document URL (HTTPS PDF/HTML). null/omit OK. When title/description are omitted, fields are extracted during orchestration.",
            "title": "Jd Url"
          },
          "languages_required": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "description": "Candidate language requirements as a JSON array (human-readable OK, e.g. English). Does not control posters.",
            "examples": [
              [
                "English",
                "Hindi"
              ]
            ],
            "title": "Languages Required"
          },
          "location": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/PartnerJobLocation"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional work location. See location.state Indian-state rule."
          },
          "openings": {
            "default": 1,
            "description": "Headcount; default 1, minimum 1",
            "minimum": 1.0,
            "title": "Openings",
            "type": "integer"
          },
          "poster_languages": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "deprecated": true,
            "description": "[Deprecated] Ignored by platform. Poster locales are automatically derived from location.state.",
            "title": "Poster Languages"
          },
          "salary": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/PartnerJobSalary"
              },
              {
                "type": "null"
              }
            ]
          },
          "shift_type": {
            "anyOf": [
              {
                "enum": [
                  "day",
                  "night",
                  "flexible"
                ],
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Only day, night, or flexible - not 'Normal Shift' / 'Afternoon Shift'",
            "title": "Shift Type"
          },
          "skills": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "description": "JSON array of strings, e.g. [\"Java\",\"Selenium\"] - not a comma-separated string",
            "examples": [
              [
                "Java",
                "Selenium"
              ]
            ],
            "title": "Skills"
          },
          "source_channels": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "description": "JSON array of strings. Internal routing hint only; not shown on Meta lead forms",
            "title": "Source Channels"
          },
          "title": {
            "anyOf": [
              {
                "maxLength": 255,
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Job title. Required unless jd_url is provided (then extracted from the JD during orchestration).",
            "title": "Title"
          }
        },
        "required": [
          "external_job_id"
        ],
        "title": "PartnerJobCreateRequest",
        "type": "object"
      },
      "PartnerJobExperience": {
        "properties": {
          "max_years": {
            "anyOf": [
              {
                "maximum": 99.0,
                "minimum": 0.0,
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Maximum years (0-99)",
            "title": "Max Years"
          },
          "min_years": {
            "anyOf": [
              {
                "maximum": 99.0,
                "minimum": 0.0,
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Minimum years (0-99)",
            "title": "Min Years"
          }
        },
        "title": "PartnerJobExperience",
        "type": "object"
      },
      "PartnerJobLocation": {
        "properties": {
          "city": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "City name (any), e.g. Bangalore or Singapore",
            "title": "City"
          },
          "country": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": "IN",
            "description": "ISO country code, e.g. IN or SG",
            "title": "Country"
          },
          "pincode": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Postal code for geo targeting",
            "title": "Pincode"
          },
          "state": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional. When set, must be a known Indian state name (e.g. Karnataka). Non-Indian values such as Singapore are rejected.",
            "title": "State"
          }
        },
        "title": "PartnerJobLocation",
        "type": "object"
      },
      "PartnerJobSalary": {
        "properties": {
          "currency": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": "INR",
            "description": "Currency code, default INR",
            "title": "Currency"
          },
          "max": {
            "anyOf": [
              {
                "minimum": 0.0,
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Maximum salary (≥ 0)",
            "title": "Max"
          },
          "min": {
            "anyOf": [
              {
                "minimum": 0.0,
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Minimum salary (≥ 0)",
            "title": "Min"
          },
          "period": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": "monthly",
            "description": "e.g. monthly, annual",
            "title": "Period"
          }
        },
        "title": "PartnerJobSalary",
        "type": "object"
      },
      "PartnerJobStatusPatchRequest": {
        "examples": [
          {
            "reason": "Hiring freeze",
            "status": "campaign_paused"
          },
          {
            "status": "campaign_live"
          },
          {
            "reason": "Role filled",
            "status": "campaign_closed"
          }
        ],
        "properties": {
          "reason": {
            "anyOf": [
              {
                "maxLength": 500,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional audit reason (pause, close, or cancel).",
            "title": "Reason"
          },
          "status": {
            "description": "Pause a live job (`campaign_paused` / `paused`). Resume a paused job that already went live (`campaign_live` / `live` / `published`). Close (`campaign_closed` / `closed`) or cancel (`campaign_cancelled` / `cancelled`). First go-live is automatic after POST /v1/jobs — PATCH live on a draft returns 410. Closed jobs cannot be reopened (409).",
            "enum": [
              "campaign_paused",
              "paused",
              "campaign_live",
              "live",
              "published",
              "campaign_closed",
              "closed",
              "campaign_cancelled",
              "cancelled"
            ],
            "examples": [
              "campaign_paused",
              "campaign_live",
              "campaign_closed"
            ],
            "title": "Status",
            "type": "string"
          }
        },
        "required": [
          "status"
        ],
        "title": "PartnerJobStatusPatchRequest",
        "type": "object"
      },
      "PartnerJobUpdateRequest": {
        "properties": {
          "description": {
            "anyOf": [
              {
                "maxLength": 50000,
                "minLength": 10,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Plain text with \\n for line breaks, or HTML using only: p, br, div, span, b, strong, em, i, u, h1-h6, ul, ol, li, blockquote, hr, table/thead/tbody/tr/th/td. No script/style/anchor tags or attributes; other tags are rejected with a 422.",
            "title": "Description"
          },
          "education": {
            "anyOf": [
              {
                "maxLength": 500,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Education"
          },
          "employment_type": {
            "anyOf": [
              {
                "maxLength": 64,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Employment Type"
          },
          "experience": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/PartnerJobExperience"
              },
              {
                "type": "null"
              }
            ]
          },
          "languages_required": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Languages Required"
          },
          "location": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/PartnerJobLocation"
              },
              {
                "type": "null"
              }
            ]
          },
          "openings": {
            "anyOf": [
              {
                "minimum": 1.0,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Openings"
          },
          "salary": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/PartnerJobSalary"
              },
              {
                "type": "null"
              }
            ]
          },
          "shift_type": {
            "anyOf": [
              {
                "enum": [
                  "day",
                  "night",
                  "flexible"
                ],
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "day, night, or flexible",
            "title": "Shift Type"
          },
          "skills": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Skills"
          },
          "title": {
            "anyOf": [
              {
                "maxLength": 255,
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Title"
          }
        },
        "title": "PartnerJobUpdateRequest",
        "type": "object"
      },
      "PartnerOfferMetrics": {
        "properties": {
          "no_response": {
            "description": "Job-level no-response count (not a per-candidate status)",
            "minimum": 0.0,
            "title": "No Response",
            "type": "integer"
          },
          "rejected": {
            "description": "Job-level rejected count",
            "minimum": 0.0,
            "title": "Rejected",
            "type": "integer"
          },
          "total_interviewed": {
            "description": "Job-level interviewed count",
            "minimum": 0.0,
            "title": "Total Interviewed",
            "type": "integer"
          },
          "total_joined": {
            "description": "Job-level joined count",
            "minimum": 0.0,
            "title": "Total Joined",
            "type": "integer"
          },
          "total_offered": {
            "description": "Job-level offered count",
            "minimum": 0.0,
            "title": "Total Offered",
            "type": "integer"
          },
          "total_selected": {
            "description": "Job-level selected count",
            "minimum": 0.0,
            "title": "Total Selected",
            "type": "integer"
          },
          "total_shortlisted": {
            "description": "Job-level shortlisted count",
            "minimum": 0.0,
            "title": "Total Shortlisted",
            "type": "integer"
          }
        },
        "required": [
          "total_shortlisted",
          "total_interviewed",
          "total_selected",
          "total_offered",
          "total_joined",
          "no_response",
          "rejected"
        ],
        "title": "PartnerOfferMetrics",
        "type": "object"
      },
      "PartnerOfferOutcomeRequest": {
        "examples": [
          {
            "campaign_id": "AIV-CAMP-99221",
            "external_job_id": "TPL-JOB-10021",
            "job_id": "AIV-JOB-77881",
            "offer_metrics": {
              "no_response": 5,
              "rejected": 8,
              "total_interviewed": 25,
              "total_joined": 12,
              "total_offered": 15,
              "total_selected": 18,
              "total_shortlisted": 40
            },
            "updated_at": "2026-06-05T18:00:00Z"
          }
        ],
        "properties": {
          "campaign_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Campaign Id"
          },
          "external_job_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "External Job Id"
          },
          "job_id": {
            "minLength": 1,
            "title": "Job Id",
            "type": "string"
          },
          "offer_metrics": {
            "$ref": "#/components/schemas/PartnerOfferMetrics"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          }
        },
        "required": [
          "job_id",
          "offer_metrics",
          "updated_at"
        ],
        "title": "PartnerOfferOutcomeRequest",
        "type": "object"
      },
      "PartnerScreeningCategory": {
        "enum": [
          "intention",
          "fitment",
          "joining"
        ],
        "title": "PartnerScreeningCategory",
        "type": "string"
      },
      "PartnerScreeningQuestionItem": {
        "properties": {
          "category": {
            "$ref": "#/components/schemas/PartnerScreeningCategory"
          },
          "criticality": {
            "anyOf": [
              {
                "maxLength": 32,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Read-only v2 criticality (e.g. hard_knockout/important/nice_to_have); additive, alongside the unchanged `is_critical`. Ignored on PATCH/PUT.",
            "title": "Criticality"
          },
          "dimension": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Real Blueprint dimension (eligibility/fitment/logistics/intent/deeper_assessment); additive, alongside the untouched legacy `category` enum -- null for partner-created items or legacy (pre-Phase-1) jobs, mirroring the employer-facing `ScreeningQuestionItem.source_dimension` field shipped in PR #650.",
            "title": "Dimension"
          },
          "disqualify_on": {
            "anyOf": [
              {
                "enum": [
                  "yes",
                  "no"
                ],
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Read-only v2: the answer (\"yes\"/\"no\") that fails this item; ignored on PATCH/PUT.",
            "title": "Disqualify On"
          },
          "is_critical": {
            "default": false,
            "title": "Is Critical",
            "type": "boolean"
          },
          "order_index": {
            "minimum": 0.0,
            "title": "Order Index",
            "type": "integer"
          },
          "question_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "UUID from agent; null for partner-added",
            "title": "Question Id"
          },
          "question_text": {
            "maxLength": 2000,
            "minLength": 1,
            "title": "Question Text",
            "type": "string"
          }
        },
        "required": [
          "question_text",
          "category",
          "order_index"
        ],
        "title": "PartnerScreeningQuestionItem",
        "type": "object"
      },
      "PartnerScreeningQuestionPatchItem": {
        "additionalProperties": false,
        "description": "Partial fields for single-question PATCH.",
        "properties": {
          "category": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/PartnerScreeningCategory"
              },
              {
                "type": "null"
              }
            ]
          },
          "is_critical": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "title": "Is Critical"
          },
          "order_index": {
            "anyOf": [
              {
                "minimum": 0.0,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Order Index"
          },
          "question_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Question Id"
          },
          "question_text": {
            "anyOf": [
              {
                "maxLength": 2000,
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Question Text"
          }
        },
        "title": "PartnerScreeningQuestionPatchItem",
        "type": "object"
      },
      "PartnerScreeningQuestionsPatchRequest": {
        "properties": {
          "order": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "description": "Reorder by question_id list (Mode C)",
            "title": "Order"
          },
          "question": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/PartnerScreeningQuestionPatchItem"
              },
              {
                "type": "null"
              }
            ]
          },
          "questions": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/PartnerScreeningQuestionItem"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Questions"
          }
        },
        "title": "PartnerScreeningQuestionsPatchRequest",
        "type": "object"
      },
      "PartnerSelectionDecisionRequest": {
        "examples": [
          {
            "decided_at": "2026-06-03T14:00:00Z",
            "decision": "offered",
            "job_id": "AIV-JOB-77881",
            "remarks": "Offer extended"
          }
        ],
        "properties": {
          "decided_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Decided At"
          },
          "decision": {
            "description": "Pipeline status written to employer_status: shortlisted, interviewed, selected, offered, joined, rejected",
            "enum": [
              "shortlisted",
              "interviewed",
              "selected",
              "offered",
              "joined",
              "rejected"
            ],
            "title": "Decision",
            "type": "string"
          },
          "job_id": {
            "description": "Aiviue job id for this application",
            "minLength": 1,
            "title": "Job Id",
            "type": "string"
          },
          "remarks": {
            "anyOf": [
              {
                "maxLength": 2000,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Remarks"
          }
        },
        "required": [
          "job_id",
          "decision"
        ],
        "title": "PartnerSelectionDecisionRequest",
        "type": "object"
      },
      "PartnerTestResetRequest": {
        "properties": {
          "tenant_id": {
            "description": "Echo back your own X-Tenant-ID as an explicit confirmation. This must exactly match the tenant resolved from the X-Tenant-ID header on this same request — it is not a separate lookup key. Required so this destructive call cannot happen from a bare POST with no body (e.g. a copy-pasted curl command missing intent).",
            "example": "tnt_a1b2c3d4",
            "minLength": 1,
            "title": "Tenant Id",
            "type": "string"
          }
        },
        "required": [
          "tenant_id"
        ],
        "title": "PartnerTestResetRequest",
        "type": "object"
      },
      "PartnerTokenResponse": {
        "properties": {
          "access_token": {
            "title": "Access Token",
            "type": "string"
          },
          "expires_in": {
            "title": "Expires In",
            "type": "integer"
          },
          "scope": {
            "title": "Scope",
            "type": "string"
          },
          "token_type": {
            "default": "Bearer",
            "title": "Token Type",
            "type": "string"
          }
        },
        "required": [
          "access_token",
          "expires_in",
          "scope"
        ],
        "title": "PartnerTokenResponse",
        "type": "object"
      },
      "PartnerTokenRevokeRequest": {
        "properties": {
          "client_id": {
            "title": "Client Id",
            "type": "string"
          },
          "client_secret": {
            "title": "Client Secret",
            "type": "string"
          }
        },
        "required": [
          "client_id",
          "client_secret"
        ],
        "title": "PartnerTokenRevokeRequest",
        "type": "object"
      },
      "PartnerTokenRevokeResponse": {
        "properties": {
          "message": {
            "default": "Client credentials revoked (v1: sets oauth client inactive)",
            "title": "Message",
            "type": "string"
          },
          "revoked": {
            "default": true,
            "title": "Revoked",
            "type": "boolean"
          }
        },
        "title": "PartnerTokenRevokeResponse",
        "type": "object"
      },
      "PartnerVoiceCategory": {
        "enum": [
          "competency",
          "situational",
          "motivational",
          "logistics"
        ],
        "title": "PartnerVoiceCategory",
        "type": "string"
      },
      "PartnerVoiceQuestionItem": {
        "properties": {
          "category": {
            "$ref": "#/components/schemas/PartnerVoiceCategory",
            "default": "competency"
          },
          "item_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Stable PSD item identity (additive; `order_index` remains the primary, fully functional identity mechanism for existing clients -- this field is never required and never replaces order_index-based mutation). Null when no real item_id exists yet (e.g. a legacy pre-Phase-1 job, or an item never routed through the identity/translation re-anchoring migration, `voice_identity_migration.py`).",
            "title": "Item Id"
          },
          "order_index": {
            "default": 0,
            "minimum": 0.0,
            "title": "Order Index",
            "type": "integer"
          },
          "probes": {
            "items": {
              "type": "string"
            },
            "title": "Probes",
            "type": "array"
          },
          "question_text": {
            "maxLength": 2000,
            "minLength": 1,
            "title": "Question Text",
            "type": "string"
          },
          "what_good_looks_like": {
            "default": "",
            "maxLength": 2000,
            "title": "What Good Looks Like",
            "type": "string"
          }
        },
        "required": [
          "question_text"
        ],
        "title": "PartnerVoiceQuestionItem",
        "type": "object"
      },
      "PartnerVoiceQuestionPatchItem": {
        "additionalProperties": false,
        "properties": {
          "category": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/PartnerVoiceCategory"
              },
              {
                "type": "null"
              }
            ]
          },
          "order_index": {
            "anyOf": [
              {
                "minimum": 0.0,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Order Index"
          },
          "probes": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Probes"
          },
          "question_text": {
            "anyOf": [
              {
                "maxLength": 2000,
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Question Text"
          },
          "what_good_looks_like": {
            "anyOf": [
              {
                "maxLength": 2000,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "What Good Looks Like"
          }
        },
        "title": "PartnerVoiceQuestionPatchItem",
        "type": "object"
      },
      "PartnerVoiceQuestionsPatchRequest": {
        "properties": {
          "expected_version": {
            "anyOf": [
              {
                "minimum": 1.0,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Job row version; optional if If-Match header is sent",
            "title": "Expected Version"
          },
          "order": {
            "anyOf": [
              {
                "items": {
                  "type": "integer"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "description": "Reorder by order_index permutation (Mode C)",
            "title": "Order"
          },
          "question": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/PartnerVoiceQuestionPatchItem"
              },
              {
                "type": "null"
              }
            ]
          },
          "questions": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/PartnerVoiceQuestionItem"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Questions"
          }
        },
        "title": "PartnerVoiceQuestionsPatchRequest",
        "type": "object"
      },
      "PartnerWebhookSubscriptionCreateRequest": {
        "properties": {
          "event_type": {
            "description": "Partner webhook event to subscribe to. One event per subscription. See API description / GET /v1/reference-data → webhook_events for the full catalog.",
            "enum": [
              "creative.ready",
              "campaign.live",
              "screening.ready",
              "voice.ready",
              "distribution.started",
              "candidate.created",
              "candidate.updated",
              "screening.started",
              "screening.completed",
              "interview.scheduled",
              "interview.completed",
              "grading.completed",
              "campaign.analytics.updated",
              "campaign.paused",
              "campaign.closed"
            ],
            "example": "candidate.created",
            "title": "Event Type",
            "type": "string"
          },
          "url": {
            "description": "Public HTTPS endpoint that returns 2xx within ~30s. Must verify X-Aiviue-Signature.",
            "example": "https://your-domain.com/webhooks/aiviue",
            "maxLength": 2048,
            "minLength": 8,
            "title": "Url",
            "type": "string"
          }
        },
        "required": [
          "event_type",
          "url"
        ],
        "title": "PartnerWebhookSubscriptionCreateRequest",
        "type": "object"
      },
      "ValidationError": {
        "properties": {
          "ctx": {
            "title": "Context",
            "type": "object"
          },
          "input": {
            "title": "Input"
          },
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "title": "Location",
            "type": "array"
          },
          "msg": {
            "title": "Message",
            "type": "string"
          },
          "type": {
            "title": "Error Type",
            "type": "string"
          }
        },
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError",
        "type": "object"
      }
    },
    "securitySchemes": {
      "OAuth2ClientCredentials": {
        "flows": {
          "clientCredentials": {
            "scopes": {
              "analytics:read": "Read partner analytics",
              "analytics:write": "Write partner analytics events",
              "candidates:read": "Read candidates and scores",
              "candidates:write": "Submit selection decisions",
              "jobs:read": "Read jobs",
              "jobs:write": "Create and update jobs",
              "partner_test:reset": "Destructive self-service reset of the caller's own partner_test environment data",
              "webhooks:manage": "Manage webhook subscriptions",
              "webhooks:read": "Read webhook subscriptions",
              "webhooks:write": "Manage webhook subscriptions"
            },
            "tokenUrl": "/v1/auth/token"
          }
        },
        "type": "oauth2"
      },
      "TenantHeader": {
        "in": "header",
        "name": "X-Tenant-ID",
        "type": "apiKey"
      }
    }
  },
  "info": {
    "contact": {
      "email": "partners@aiviue.com",
      "name": "Aiviue Partner Engineering"
    },
    "description": "Production-grade hiring workflow integration for HCM/ATS partners.\n\n**Interactive docs:** [Swagger UI](https://api.aiviue.com/v1/docs) · [ReDoc](https://api.aiviue.com/v1/redoc) · [OpenAPI JSON](https://api.aiviue.com/v1/openapi.json)\n\n**Authentication:** OAuth 2.0 Client Credentials (RS256 JWT). Client secrets are prefixed by environment\n(`aiv_test_…` for `partner_test`, `aiv_live_…` for production) — `client_id` is optional when\nauthenticating with a prefixed secret, since the prefix and secret alone resolve the client. Existing\nproduction clients issued before this format have no prefix and continue to work unchanged.\n\n**Using the Authorize button below:** the `client_id` field can be left blank if your `client_secret`\nis `aiv_test_…`- or `aiv_live_…`-prefixed — enter only `client_secret` and the scopes you need.\n\n**Tenant scoping:** `X-Tenant-ID` header on resource routes.\n\n**Write requests:** `X-Idempotency-Key` header required on POST/PUT/PATCH/DELETE.\n\n**Partner base URL:** `https://api.aiviue.com/v1`\n\n## Webhooks (partner receives events from Aiviue)\n\nPartners **subscribe** to outbound events with `POST /v1/webhooks/subscriptions` (`webhooks:write`).\nList subscriptions with `GET /v1/webhooks/subscriptions`. Delivery log: `GET /v1/webhooks/deliveries`.\nA `scores` object in a webhook payload follows the same plan-tier gate as `GET /v1/candidates/{candidate_id}/scores`.\n\n### Subscribable webhook events\n\nRegister **one `event_type` per** `POST /v1/webhooks/subscriptions` call. Use the same HTTPS URL for multiple events by creating multiple subscriptions.\n\nAlternative: set per-job `callback_urls` on `POST /v1/jobs` (see callback key column).\n\n| `event_type` | Phase | When fired | `callback_urls` key |\n|--------------|-------|------------|---------------------|\n| `creative.ready` | Job orchestration | A job poster/creative asset was generated and auto-published (per locale). | `creative_ready` |\n| `screening.ready` | Job orchestration | WhatsApp/chat screening questions are generated and published for the job. | `candidate_update` |\n| `voice.ready` | Job orchestration | Voice interview questions are generated and saved on the job. | `candidate_update` |\n| `campaign.live` | Job orchestration | The job campaign is published live (core pipeline complete). | `creative_ready` |\n| `distribution.started` | Distribution | Meta lead-ad distribution started successfully after campaign is live. | `analytics_update` |\n| `candidate.created` | Candidate funnel | A new candidate applied to a partner job (new application). | `candidate_update` |\n| `candidate.updated` | Candidate funnel | An existing application status or profile projection changed. | `candidate_update` |\n| `screening.started` | Candidate funnel | The candidate started screening for a job (chat or AI voice). | `candidate_update` |\n| `screening.completed` | Candidate funnel | The candidate finished screening (chat or AI voice). | `candidate_update` |\n| `interview.scheduled` | Candidate funnel | An AI voice interview was scheduled or outbound dial initiated. | `candidate_update` |\n| `interview.completed` | Candidate funnel | The AI voice interview finished (transcript saved). | `candidate_update` |\n| `grading.completed` | Candidate funnel | AI scores are finalized for an application (fit, intent, etc.). | `grading_update` |\n| `campaign.analytics.updated` | Campaign lifecycle | Campaign or offer-funnel analytics were updated (partner-reported or aggregated). | `analytics_update` |\n| `campaign.paused` | Campaign lifecycle | The job/campaign was paused via partner status API or platform action. | — |\n| `campaign.closed` | Campaign lifecycle | The job/campaign was closed. | — |\n\n**Scope:** `webhooks:write` to create/delete subscriptions; `webhooks:read` to list subscriptions and deliveries.\n\n**Also available:** `GET /v1/reference-data` returns `webhook_subscribable_event_types` and `webhook_events` (full catalog with descriptions).",
    "license": {
      "name": "Proprietary"
    },
    "title": "Aiviue Partner API",
    "version": "1.1.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/v1/admin/reset": {
      "post": {
        "description": "**partner_test environment only.** Deletes every Job/JobApplication created under your tenant, and your rows in the webhook, audit-log, external-ref, offer-outcome, and selection-decision tables. Does **not** delete your OAuth client or tenant record — you can keep using the same credentials immediately after this call. Requires the `tenant_id` field in the request body to exactly match your X-Tenant-ID header, as an explicit confirmation.",
        "operationId": "reset_partner_test_environment_v1_admin_reset_post",
        "parameters": [
          {
            "description": "Unique key per logical write. Reuse with the same body returns the cached response; reuse with a different body returns 409 IDEMPOTENCY_CONFLICT.",
            "in": "header",
            "name": "X-Idempotency-Key",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          },
          {
            "description": "Partner tenant identifier from onboarding (e.g. tnt_aiviue_aicolegion). Required on all protected resource routes.",
            "in": "header",
            "name": "X-Tenant-ID",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PartnerTestResetRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "OAuth2ClientCredentials": [],
            "TenantHeader": []
          }
        ],
        "summary": "Reset this partner's partner_test data",
        "tags": [
          "Partner Admin"
        ]
      }
    },
    "/v1/analytics/offer-outcome": {
      "post": {
        "description": "Store a partner-reported snapshot for one job in `partner_offer_outcomes`. `offer_metrics` counts: `total_shortlisted`, `total_interviewed`, `total_selected`, `total_offered`, `total_joined`, `no_response`, `rejected`. Does not update candidate rows or employer job tiles. `no_response` exists only on this payload. Scope: `analytics:write`. Requires `X-Idempotency-Key`.",
        "operationId": "post_offer_outcome_v1_analytics_offer_outcome_post",
        "parameters": [
          {
            "description": "Unique key per logical write. Reuse with the same body returns the cached response; reuse with a different body returns 409 IDEMPOTENCY_CONFLICT.",
            "in": "header",
            "name": "X-Idempotency-Key",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          },
          {
            "description": "Partner tenant identifier from onboarding (e.g. tnt_aiviue_aicolegion). Required on all protected resource routes.",
            "in": "header",
            "name": "X-Tenant-ID",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PartnerOfferOutcomeRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "OAuth2ClientCredentials": [],
            "TenantHeader": []
          }
        ],
        "summary": "Report per-job pipeline metrics",
        "tags": [
          "Partner Analytics"
        ]
      }
    },
    "/v1/auth/.well-known/jwks.json": {
      "get": {
        "operationId": "partner_jwks_v1_auth__well_known_jwks_json_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response Partner Jwks V1 Auth  Well Known Jwks Json Get",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "security": [],
        "summary": "Partner Jwks",
        "tags": [
          "Partner Auth"
        ]
      }
    },
    "/v1/auth/token": {
      "post": {
        "operationId": "partner_token_v1_auth_token_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "client_id": {
                    "description": "OAuth client_id issued during partner onboarding. Optional when authenticating with an aiv_test_/aiv_live_ prefixed secret — the prefix and secret alone resolve the client.",
                    "example": "tapplent_sandbox_client",
                    "type": "string"
                  },
                  "client_secret": {
                    "description": "OAuth client_secret issued during partner onboarding. New-format secrets are environment-prefixed (aiv_test_… / aiv_live_…); legacy production secrets issued before this format have no prefix.",
                    "example": "aiv_test_7b2e9c4a1f8d6b3e0c5a9f2d7b4e1c8f",
                    "format": "password",
                    "type": "string"
                  },
                  "grant_type": {
                    "description": "Must be client_credentials",
                    "example": "client_credentials",
                    "type": "string"
                  }
                },
                "required": [
                  "grant_type",
                  "client_secret"
                ],
                "type": "object"
              }
            },
            "application/x-www-form-urlencoded": {
              "schema": {
                "properties": {
                  "client_id": {
                    "description": "OAuth client_id issued during partner onboarding. Optional when authenticating with an aiv_test_/aiv_live_ prefixed secret — the prefix and secret alone resolve the client.",
                    "example": "tapplent_sandbox_client",
                    "type": "string"
                  },
                  "client_secret": {
                    "description": "OAuth client_secret issued during partner onboarding. New-format secrets are environment-prefixed (aiv_test_… / aiv_live_…); legacy production secrets issued before this format have no prefix.",
                    "example": "aiv_test_7b2e9c4a1f8d6b3e0c5a9f2d7b4e1c8f",
                    "format": "password",
                    "type": "string"
                  },
                  "grant_type": {
                    "description": "Must be client_credentials",
                    "example": "client_credentials",
                    "type": "string"
                  }
                },
                "required": [
                  "grant_type",
                  "client_secret"
                ],
                "type": "object"
              }
            }
          },
          "description": "OAuth 2.0 client credentials. The API also accepts application/x-www-form-urlencoded or Authorization: Basic (client_secret_basic).",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerTokenResponse"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "security": [],
        "summary": "Partner Token",
        "tags": [
          "Partner Auth"
        ]
      }
    },
    "/v1/auth/token/revoke": {
      "post": {
        "operationId": "partner_token_revoke_v1_auth_token_revoke_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PartnerTokenRevokeRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerTokenRevokeResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [],
        "summary": "Partner Token Revoke",
        "tags": [
          "Partner Auth"
        ]
      }
    },
    "/v1/auth/validate": {
      "get": {
        "description": "Protected sanity check for issued tokens (Sprint 1.3).",
        "operationId": "partner_auth_validate_v1_auth_validate_get",
        "parameters": [
          {
            "description": "Partner tenant identifier from onboarding (e.g. tnt_aiviue_aicolegion). Required on all protected resource routes.",
            "in": "header",
            "name": "X-Tenant-ID",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PartnerAuthValidateResponse"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "security": [
          {
            "OAuth2ClientCredentials": [],
            "TenantHeader": []
          }
        ],
        "summary": "Partner Auth Validate",
        "tags": [
          "Partner Auth"
        ]
      }
    },
    "/v1/candidates/{candidate_id}": {
      "get": {
        "description": "Profile (name, email, mobile, skills, status) — **no resume file**. `email` is null when the candidate has not provided one. `job_id` is optional unless the candidate has more than one application. Download the CV with `GET /v1/candidates/{candidate_id}/resume?job_id=…`. Scope: `candidates:read`.",
        "operationId": "get_candidate_v1_candidates__candidate_id__get",
        "parameters": [
          {
            "in": "path",
            "name": "candidate_id",
            "required": true,
            "schema": {
              "title": "Candidate Id",
              "type": "string"
            }
          },
          {
            "description": "Disambiguate when candidate has multiple applications",
            "in": "query",
            "name": "job_id",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Disambiguate when candidate has multiple applications",
              "title": "Job Id"
            }
          },
          {
            "description": "Partner tenant identifier from onboarding (e.g. tnt_aiviue_aicolegion). Required on all protected resource routes.",
            "in": "header",
            "name": "X-Tenant-ID",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "application_id": "app_uuid",
                    "applied_at": "2026-06-01T10:00:00Z",
                    "candidate_id": "AIV-CAND-55661",
                    "current_location": "Pune",
                    "email": "priya@example.com",
                    "employer_status": "shortlisted",
                    "job_id": "AIV-JOB-77881",
                    "mobile": "9876543210",
                    "name": "Priya Sharma",
                    "partner_stage": null,
                    "screening_status": "completed",
                    "skills": [
                      "picking",
                      "packing"
                    ]
                  },
                  "error": null,
                  "meta": {},
                  "success": true
                },
                "schema": {
                  "$ref": "#/components/schemas/PartnerCandidateProfileResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "OAuth2ClientCredentials": [],
            "TenantHeader": []
          }
        ],
        "summary": "Get candidate profile",
        "tags": [
          "Partner Candidates"
        ]
      }
    },
    "/v1/candidates/{candidate_id}/interviews": {
      "get": {
        "description": "Voice screening calls for a candidate. Each interview includes:\n- `recording_url` — Voice call recording\n- `score.voicefit` — Voice communication quality (0–100)\n- `score.overall_score`, `score.fitment_score`, `score.intention_score`, `score.joining_score` — Voice screening aggregate scores\n- `summary` — Brief call summary\n\n`score` fields follow the same plan-tier gate as `/scores` (`voicefit` needs pro or enterprise); fields the tier can't see are null.\n\nScope: `candidates:read`.",
        "operationId": "list_candidate_interviews_v1_candidates__candidate_id__interviews_get",
        "parameters": [
          {
            "in": "path",
            "name": "candidate_id",
            "required": true,
            "schema": {
              "title": "Candidate Id",
              "type": "string"
            }
          },
          {
            "description": "Filter interviews for a specific job",
            "in": "query",
            "name": "job_id",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Filter interviews for a specific job",
              "title": "Job Id"
            }
          },
          {
            "description": "Partner tenant identifier from onboarding (e.g. tnt_aiviue_aicolegion). Required on all protected resource routes.",
            "in": "header",
            "name": "X-Tenant-ID",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "OAuth2ClientCredentials": [],
            "TenantHeader": []
          }
        ],
        "summary": "List voice screening interviews",
        "tags": [
          "Partner Candidates"
        ]
      }
    },
    "/v1/candidates/{candidate_id}/resume": {
      "get": {
        "description": "Returns a time-limited `resume_url` plus `mime_type` and `file_name` so partners download PDF vs image the same way employers do. `job_id` is required. Scope: `candidates:read`. 404 when the candidate/application is not visible or there is no resume file; 503 `SERVICE_UNAVAILABLE` when the signed URL cannot be minted (retry; the API never returns an unsigned storage URL). Do not persist `resume_url`; fetch again when expired.",
        "operationId": "get_candidate_resume_v1_candidates__candidate_id__resume_get",
        "parameters": [
          {
            "in": "path",
            "name": "candidate_id",
            "required": true,
            "schema": {
              "title": "Candidate Id",
              "type": "string"
            }
          },
          {
            "description": "Job id (AIV-JOB-* or UUID) for this application",
            "in": "query",
            "name": "job_id",
            "required": true,
            "schema": {
              "description": "Job id (AIV-JOB-* or UUID) for this application",
              "title": "Job Id",
              "type": "string"
            }
          },
          {
            "description": "Partner tenant identifier from onboarding (e.g. tnt_aiviue_aicolegion). Required on all protected resource routes.",
            "in": "header",
            "name": "X-Tenant-ID",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "application_id": "app_uuid",
                    "candidate_id": "AIV-CAND-55661",
                    "expires_in": 600,
                    "file_kind": "document",
                    "file_name": "Priya_Sharma.pdf",
                    "job_id": "AIV-JOB-77881",
                    "mime_type": "application/pdf",
                    "resume_url": "https://example.supabase.co/storage/v1/object/sign/resumes/cv.pdf?token=…"
                  },
                  "error": null,
                  "meta": {},
                  "success": true
                },
                "schema": {
                  "$ref": "#/components/schemas/PartnerCandidateResumeResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "OAuth2ClientCredentials": [],
            "TenantHeader": []
          }
        ],
        "summary": "Get signed resume download URL",
        "tags": [
          "Partner Candidates"
        ]
      }
    },
    "/v1/candidates/{candidate_id}/scores": {
      "get": {
        "description": "Final combined candidate scores (Chat + Voice merged when both completed).\n\n**Canonical score fields** (recommended):\n- `overall_score` — Weighted overall score (0–100)\n- `fitment_score` — Skills/experience fitment pillar (0–100)\n- `intention_score` — Motivation/interest pillar (0–100)\n- `joining_score` — Numeric joining likelihood (0–100)\n- `joining_probability` — Categorical interpretation: `low` / `medium` / `high`\n- `voicefit_score` — Voice communication quality, per-call metric (0–100)\n- `grade` — Overall band: `perfect` / `high` / `medium` / `low`\n\n**Legacy fields** (preserved for backward compatibility):\n- `fit_score` — Holds the overall score (not fitment). `fit_score.components.experience_match` holds fitment.\n- `intent_score` — Same value as `intention_score`.\n\nAggregate scores are gated by the tenant's plan tier: free/starter get `overall_score` (and legacy `fit_score`); growth adds `intention_score`/`intent_score`; pro/enterprise get every score. `grade` is returned on every tier.\n\nScoring 2.0 jobs: `eligibility` (must-haves pass/fail/unverified) on every tier. On jobs created with the pillar model, `overall_score` and `fit_score` = 0.6 fitment + 0.25 joining + 0.15 intention (0 when a must-have fails), `fitment_score` is the fitment pillar, and `intention_score`/`joining_score` come from the intent and logistics answers (same tier gates). Older jobs keep fitment as the overall score and omit intention/joining.\n\nScope: `candidates:read`.",
        "operationId": "get_candidate_scores_v1_candidates__candidate_id__scores_get",
        "parameters": [
          {
            "in": "path",
            "name": "candidate_id",
            "required": true,
            "schema": {
              "title": "Candidate Id",
              "type": "string"
            }
          },
          {
            "description": "Job id (AIV-JOB-* or UUID) for this application",
            "in": "query",
            "name": "job_id",
            "required": true,
            "schema": {
              "description": "Job id (AIV-JOB-* or UUID) for this application",
              "title": "Job Id",
              "type": "string"
            }
          },
          {
            "description": "Partner tenant identifier from onboarding (e.g. tnt_aiviue_aicolegion). Required on all protected resource routes.",
            "in": "header",
            "name": "X-Tenant-ID",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "OAuth2ClientCredentials": [],
            "TenantHeader": []
          }
        ],
        "summary": "Get candidate screening scores",
        "tags": [
          "Partner Candidates"
        ]
      }
    },
    "/v1/candidates/{candidate_id}/screening": {
      "get": {
        "description": "Individual question/answer data plus screening aggregate scores.\n\n**Each question** includes:\n- `question_id` — Unique question identifier\n- `question_text` — The question asked\n- `question_type` — Category: `fitment`, `intention`, or `joining` (Chat); `competency`, `situational`, `motivational`, `logistics` (Voice)\n- `candidate_response` — Candidate's answer text (raw, in the language they answered)\n- `employer_answer_en` — English rendering of the answer for hiring managers (equals `candidate_response` for English answers; null when no translation is available)\n- `employer_answer_provenance` — `english_original` | `translated` | `canonical_fallback` | `unavailable`\n- `response_score` — Individual answer score (0–100)\n- `recording_url` — Voice recording URL (present only for voice answers)\n\n**Screening aggregate scores** (when screening is complete):\n- `overall_score`, `fitment_score`, `intention_score`, `joining_score`, `grade`\n\nThe aggregate scores follow the same plan-tier gate as `/scores` (`grade` is always returned). Per-question `response_score` is returned on every tier.\n\nScope: `candidates:read`.",
        "operationId": "get_candidate_screening_v1_candidates__candidate_id__screening_get",
        "parameters": [
          {
            "in": "path",
            "name": "candidate_id",
            "required": true,
            "schema": {
              "title": "Candidate Id",
              "type": "string"
            }
          },
          {
            "description": "Job id (AIV-JOB-* or UUID) for this application",
            "in": "query",
            "name": "job_id",
            "required": true,
            "schema": {
              "description": "Job id (AIV-JOB-* or UUID) for this application",
              "title": "Job Id",
              "type": "string"
            }
          },
          {
            "description": "Partner tenant identifier from onboarding (e.g. tnt_aiviue_aicolegion). Required on all protected resource routes.",
            "in": "header",
            "name": "X-Tenant-ID",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "OAuth2ClientCredentials": [],
            "TenantHeader": []
          }
        ],
        "summary": "Get candidate screening answers",
        "tags": [
          "Partner Candidates"
        ]
      }
    },
    "/v1/candidates/{candidate_id}/selection-decision": {
      "post": {
        "description": "Set the hiring pipeline status for one candidate on one job. Writes `job_applications.employer_status` with the same values as the employer dashboard: `shortlisted`, `interviewed`, `selected`, `offered`, `joined`, `rejected`. Last write wins. Does not notify the candidate on reject. Scope: `candidates:write`. Requires `X-Idempotency-Key`.",
        "operationId": "submit_selection_decision_v1_candidates__candidate_id__selection_decision_post",
        "parameters": [
          {
            "in": "path",
            "name": "candidate_id",
            "required": true,
            "schema": {
              "title": "Candidate Id",
              "type": "string"
            }
          },
          {
            "description": "Unique key per logical write. Reuse with the same body returns the cached response; reuse with a different body returns 409 IDEMPOTENCY_CONFLICT.",
            "in": "header",
            "name": "X-Idempotency-Key",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          },
          {
            "description": "Partner tenant identifier from onboarding (e.g. tnt_aiviue_aicolegion). Required on all protected resource routes.",
            "in": "header",
            "name": "X-Tenant-ID",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PartnerSelectionDecisionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "OAuth2ClientCredentials": [],
            "TenantHeader": []
          }
        ],
        "summary": "Submit candidate pipeline status",
        "tags": [
          "Partner Candidates"
        ]
      }
    },
    "/v1/integration/health": {
      "get": {
        "description": "Optional auth — liveness for load balancers and partner monitors.",
        "operationId": "partner_integration_health_v1_integration_health_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": {
                    "type": "string"
                  },
                  "title": "Response Partner Integration Health V1 Integration Health Get",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "security": [],
        "summary": "Partner Integration Health",
        "tags": [
          "Partner Integration"
        ]
      }
    },
    "/v1/integration/health/detailed": {
      "get": {
        "description": "Bearer required — DB + Redis connectivity.",
        "operationId": "partner_integration_health_detailed_v1_integration_health_detailed_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response Partner Integration Health Detailed V1 Integration Health Detailed Get",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          }
        },
        "security": [
          {
            "OAuth2ClientCredentials": []
          }
        ],
        "summary": "Partner Integration Health Detailed",
        "tags": [
          "Partner Integration"
        ]
      }
    },
    "/v1/interviews/{interview_id}": {
      "get": {
        "operationId": "get_interview_v1_interviews__interview_id__get",
        "parameters": [
          {
            "in": "path",
            "name": "interview_id",
            "required": true,
            "schema": {
              "title": "Interview Id",
              "type": "string"
            }
          },
          {
            "description": "Partner tenant identifier from onboarding (e.g. tnt_aiviue_aicolegion). Required on all protected resource routes.",
            "in": "header",
            "name": "X-Tenant-ID",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "OAuth2ClientCredentials": [],
            "TenantHeader": []
          }
        ],
        "summary": "Get Interview",
        "tags": [
          "Partner Interviews"
        ]
      }
    },
    "/v1/jobs": {
      "get": {
        "operationId": "list_partner_jobs_v1_jobs_get",
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 50,
              "maximum": 100,
              "minimum": 1,
              "title": "Limit",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Cursor"
            }
          },
          {
            "description": "Partner tenant identifier from onboarding (e.g. tnt_aiviue_aicolegion). Required on all protected resource routes.",
            "in": "header",
            "name": "X-Tenant-ID",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "OAuth2ClientCredentials": [],
            "TenantHeader": []
          }
        ],
        "summary": "List Partner Jobs",
        "tags": [
          "Partner Jobs"
        ]
      },
      "post": {
        "description": "Push JD / create job + campaign (Tapplent-compatible).\n\n**Poster locales:** Poster and ad locales are automatically derived by the platform from `location.state` (e.g. Maharashtra -> Marathi). `poster_languages` and `ad_generation_language` are deprecated and ignored.\n\n**Payload hints:** `description` ≥ 10 chars when no `jd_url`; `skills` must be a JSON string array (not comma-separated); `shift_type` only `day`|`night`|`flexible`; `location.state` must be a known Indian state when set (omit state for non-India cities such as Singapore). Validation errors return a specific `error.message` (never `None`).",
        "operationId": "partner_create_job_v1_jobs_post",
        "parameters": [
          {
            "description": "Unique key per logical write. Reuse with the same body returns the cached response; reuse with a different body returns 409 IDEMPOTENCY_CONFLICT.",
            "in": "header",
            "name": "X-Idempotency-Key",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          },
          {
            "description": "Partner tenant identifier from onboarding (e.g. tnt_aiviue_aicolegion). Required on all protected resource routes.",
            "in": "header",
            "name": "X-Tenant-ID",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PartnerJobCreateRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "400": {
            "description": "Validation error with actionable `error.message` - e.g. short description, invalid `skills` type, invalid `location.state`, `JD_URL_NOT_ALLOWED`."
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "OAuth2ClientCredentials": [
              "jobs:write"
            ],
            "TenantHeader": []
          }
        ],
        "summary": "Partner Create Job",
        "tags": [
          "Partner Jobs"
        ]
      }
    },
    "/v1/jobs/{job_id}": {
      "get": {
        "operationId": "get_partner_job_v1_jobs__job_id__get",
        "parameters": [
          {
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "title": "Job Id",
              "type": "string"
            }
          },
          {
            "description": "Partner tenant identifier from onboarding (e.g. tnt_aiviue_aicolegion). Required on all protected resource routes.",
            "in": "header",
            "name": "X-Tenant-ID",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "OAuth2ClientCredentials": [],
            "TenantHeader": []
          }
        ],
        "summary": "Get Partner Job",
        "tags": [
          "Partner Jobs"
        ]
      },
      "put": {
        "operationId": "update_partner_job_v1_jobs__job_id__put",
        "parameters": [
          {
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "title": "Job Id",
              "type": "string"
            }
          },
          {
            "description": "Unique key per logical write. Reuse with the same body returns the cached response; reuse with a different body returns 409 IDEMPOTENCY_CONFLICT.",
            "in": "header",
            "name": "X-Idempotency-Key",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          },
          {
            "description": "Partner tenant identifier from onboarding (e.g. tnt_aiviue_aicolegion). Required on all protected resource routes.",
            "in": "header",
            "name": "X-Tenant-ID",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PartnerJobUpdateRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "OAuth2ClientCredentials": [],
            "TenantHeader": []
          }
        ],
        "summary": "Update Partner Job",
        "tags": [
          "Partner Jobs"
        ]
      }
    },
    "/v1/jobs/{job_id}/candidates": {
      "get": {
        "operationId": "list_job_candidates_v1_jobs__job_id__candidates_get",
        "parameters": [
          {
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "title": "Job Id",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 50,
              "maximum": 500,
              "minimum": 1,
              "title": "Limit",
              "type": "integer"
            }
          },
          {
            "description": "Opaque pagination cursor from previous response",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Opaque pagination cursor from previous response",
              "title": "Cursor"
            }
          },
          {
            "description": "Partner tenant identifier from onboarding (e.g. tnt_aiviue_aicolegion). Required on all protected resource routes.",
            "in": "header",
            "name": "X-Tenant-ID",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "OAuth2ClientCredentials": [],
            "TenantHeader": []
          }
        ],
        "summary": "List Job Candidates",
        "tags": [
          "Partner Jobs"
        ]
      }
    },
    "/v1/jobs/{job_id}/screening-questions": {
      "get": {
        "description": "List screening questions for a job. Each question includes `question_id`, `question_text`, `category` (`intention`/`fitment`/`joining`), `is_critical`, and `order_index`. Scope: `jobs:read`.",
        "operationId": "get_partner_screening_questions_v1_jobs__job_id__screening_questions_get",
        "parameters": [
          {
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "title": "Job Id",
              "type": "string"
            }
          },
          {
            "description": "Partner tenant identifier from onboarding (e.g. tnt_aiviue_aicolegion). Required on all protected resource routes.",
            "in": "header",
            "name": "X-Tenant-ID",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "OAuth2ClientCredentials": [],
            "TenantHeader": []
          }
        ],
        "summary": "Get Partner Screening Questions",
        "tags": [
          "Partner Job Questions"
        ]
      },
      "patch": {
        "operationId": "patch_partner_screening_questions_v1_jobs__job_id__screening_questions_patch",
        "parameters": [
          {
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "title": "Job Id",
              "type": "string"
            }
          },
          {
            "description": "Unique key per logical write. Reuse with the same body returns the cached response; reuse with a different body returns 409 IDEMPOTENCY_CONFLICT.",
            "in": "header",
            "name": "X-Idempotency-Key",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          },
          {
            "description": "Partner tenant identifier from onboarding (e.g. tnt_aiviue_aicolegion). Required on all protected resource routes.",
            "in": "header",
            "name": "X-Tenant-ID",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PartnerScreeningQuestionsPatchRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "OAuth2ClientCredentials": [],
            "TenantHeader": []
          }
        ],
        "summary": "Patch Partner Screening Questions",
        "tags": [
          "Partner Job Questions"
        ]
      },
      "post": {
        "description": "Add a single screening question to a job. Provide `question_text`, `category`, `is_critical`, and `order_index`. The question is published to WhatsApp screening after creation. Scope: `jobs:write`. Requires `X-Idempotency-Key`.",
        "operationId": "create_partner_screening_question_v1_jobs__job_id__screening_questions_post",
        "parameters": [
          {
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "title": "Job Id",
              "type": "string"
            }
          },
          {
            "description": "Unique key per logical write. Reuse with the same body returns the cached response; reuse with a different body returns 409 IDEMPOTENCY_CONFLICT.",
            "in": "header",
            "name": "X-Idempotency-Key",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          },
          {
            "description": "Partner tenant identifier from onboarding (e.g. tnt_aiviue_aicolegion). Required on all protected resource routes.",
            "in": "header",
            "name": "X-Tenant-ID",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PartnerScreeningQuestionItem"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "OAuth2ClientCredentials": [],
            "TenantHeader": []
          }
        ],
        "summary": "Add a single screening question",
        "tags": [
          "Partner Job Questions"
        ]
      }
    },
    "/v1/jobs/{job_id}/screening-questions/{question_id}": {
      "delete": {
        "description": "Delete a single screening question by `question_id`. Remaining questions are re-indexed and re-published. Scope: `jobs:write`. Requires `X-Idempotency-Key`.",
        "operationId": "delete_partner_screening_question_v1_jobs__job_id__screening_questions__question_id__delete",
        "parameters": [
          {
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "title": "Job Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "question_id",
            "required": true,
            "schema": {
              "title": "Question Id",
              "type": "string"
            }
          },
          {
            "description": "Unique key per logical write. Reuse with the same body returns the cached response; reuse with a different body returns 409 IDEMPOTENCY_CONFLICT.",
            "in": "header",
            "name": "X-Idempotency-Key",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          },
          {
            "description": "Partner tenant identifier from onboarding (e.g. tnt_aiviue_aicolegion). Required on all protected resource routes.",
            "in": "header",
            "name": "X-Tenant-ID",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "OAuth2ClientCredentials": [],
            "TenantHeader": []
          }
        ],
        "summary": "Delete a single screening question",
        "tags": [
          "Partner Job Questions"
        ]
      }
    },
    "/v1/jobs/{job_id}/status": {
      "patch": {
        "description": "**Pause** a live job: `{ \"status\": \"campaign_paused\" }` (alias `paused`).\n\n**Resume** a paused job: `{ \"status\": \"campaign_live\" }` (aliases `live`, `published`). Allowed only if the job was live before, then paused. Does not regenerate posters or re-run Meta.\n\n**Close:** `{ \"status\": \"campaign_closed\" }` (aliases `closed`, `cancelled`). Closed cannot be reopened (409).\n\n**First go-live** is automatic after `POST /v1/jobs`. PATCH live on a draft returns **410** `CAMPAIGN_LIVE_DEPRECATED`.\n\nScope: `jobs:write`. Requires `X-Idempotency-Key`.",
        "operationId": "patch_partner_job_status_v1_jobs__job_id__status_patch",
        "parameters": [
          {
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "title": "Job Id",
              "type": "string"
            }
          },
          {
            "description": "Unique key per logical write. Reuse with the same body returns the cached response; reuse with a different body returns 409 IDEMPOTENCY_CONFLICT.",
            "in": "header",
            "name": "X-Idempotency-Key",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          },
          {
            "description": "Partner tenant identifier from onboarding (e.g. tnt_aiviue_aicolegion). Required on all protected resource routes.",
            "in": "header",
            "name": "X-Tenant-ID",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "examples": {
                "close": {
                  "summary": "Close a campaign (final)",
                  "value": {
                    "reason": "Role filled",
                    "status": "campaign_closed"
                  }
                },
                "pause": {
                  "summary": "Pause a live campaign",
                  "value": {
                    "reason": "Hiring freeze",
                    "status": "campaign_paused"
                  }
                },
                "resume": {
                  "summary": "Resume a paused campaign",
                  "value": {
                    "status": "campaign_live"
                  }
                }
              },
              "schema": {
                "$ref": "#/components/schemas/PartnerJobStatusPatchRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "OAuth2ClientCredentials": [],
            "TenantHeader": []
          }
        ],
        "summary": "Pause, resume, or close a job",
        "tags": [
          "Partner Jobs"
        ]
      }
    },
    "/v1/jobs/{job_id}/voice-questions": {
      "get": {
        "description": "List voice screening questions for a job. Each includes `question_text`, `category` (`competency`/`situational`/`motivational`/`logistics`), `probes`, `what_good_looks_like`, and `order_index`. Returns an `ETag` header for optimistic concurrency. Scope: `jobs:read`.",
        "operationId": "get_partner_voice_questions_v1_jobs__job_id__voice_questions_get",
        "parameters": [
          {
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "title": "Job Id",
              "type": "string"
            }
          },
          {
            "description": "Partner tenant identifier from onboarding (e.g. tnt_aiviue_aicolegion). Required on all protected resource routes.",
            "in": "header",
            "name": "X-Tenant-ID",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "OAuth2ClientCredentials": [],
            "TenantHeader": []
          }
        ],
        "summary": "Get Partner Voice Questions",
        "tags": [
          "Partner Job Questions"
        ]
      },
      "patch": {
        "operationId": "patch_partner_voice_questions_v1_jobs__job_id__voice_questions_patch",
        "parameters": [
          {
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "title": "Job Id",
              "type": "string"
            }
          },
          {
            "description": "Unique key per logical write. Reuse with the same body returns the cached response; reuse with a different body returns 409 IDEMPOTENCY_CONFLICT.",
            "in": "header",
            "name": "X-Idempotency-Key",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          },
          {
            "description": "Partner tenant identifier from onboarding (e.g. tnt_aiviue_aicolegion). Required on all protected resource routes.",
            "in": "header",
            "name": "X-Tenant-ID",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PartnerVoiceQuestionsPatchRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "OAuth2ClientCredentials": [],
            "TenantHeader": []
          }
        ],
        "summary": "Patch Partner Voice Questions",
        "tags": [
          "Partner Job Questions"
        ]
      },
      "post": {
        "description": "Add a single voice screening question. Provide `question_text`, `category`, `probes`, and `what_good_looks_like`. Scope: `jobs:write`. Requires `X-Idempotency-Key`.",
        "operationId": "create_partner_voice_question_v1_jobs__job_id__voice_questions_post",
        "parameters": [
          {
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "title": "Job Id",
              "type": "string"
            }
          },
          {
            "description": "Unique key per logical write. Reuse with the same body returns the cached response; reuse with a different body returns 409 IDEMPOTENCY_CONFLICT.",
            "in": "header",
            "name": "X-Idempotency-Key",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          },
          {
            "description": "Partner tenant identifier from onboarding (e.g. tnt_aiviue_aicolegion). Required on all protected resource routes.",
            "in": "header",
            "name": "X-Tenant-ID",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PartnerVoiceQuestionItem"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "OAuth2ClientCredentials": [],
            "TenantHeader": []
          }
        ],
        "summary": "Add a single voice question",
        "tags": [
          "Partner Job Questions"
        ]
      }
    },
    "/v1/jobs/{job_id}/voice-questions/{order_index}": {
      "delete": {
        "description": "Delete a single voice question by `order_index`. Remaining questions are re-indexed. Scope: `jobs:write`. Requires `X-Idempotency-Key`.",
        "operationId": "delete_partner_voice_question_v1_jobs__job_id__voice_questions__order_index__delete",
        "parameters": [
          {
            "in": "path",
            "name": "job_id",
            "required": true,
            "schema": {
              "title": "Job Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "order_index",
            "required": true,
            "schema": {
              "title": "Order Index",
              "type": "integer"
            }
          },
          {
            "description": "Unique key per logical write. Reuse with the same body returns the cached response; reuse with a different body returns 409 IDEMPOTENCY_CONFLICT.",
            "in": "header",
            "name": "X-Idempotency-Key",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          },
          {
            "description": "Partner tenant identifier from onboarding (e.g. tnt_aiviue_aicolegion). Required on all protected resource routes.",
            "in": "header",
            "name": "X-Tenant-ID",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "OAuth2ClientCredentials": [],
            "TenantHeader": []
          }
        ],
        "summary": "Delete a single voice question by order_index",
        "tags": [
          "Partner Job Questions"
        ]
      }
    },
    "/v1/reference-data": {
      "get": {
        "description": "Includes `webhook_subscribable_event_types` (flat list) and `webhook_events` (full catalog with `phase`, `when_fired`, `callback_url_key`).",
        "operationId": "get_partner_reference_data_v1_reference_data_get",
        "parameters": [
          {
            "description": "Partner tenant identifier from onboarding (e.g. tnt_aiviue_aicolegion). Required on all protected resource routes.",
            "in": "header",
            "name": "X-Tenant-ID",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          }
        },
        "security": [
          {
            "OAuth2ClientCredentials": [],
            "TenantHeader": []
          }
        ],
        "summary": "Get Partner Reference Data",
        "tags": [
          "Partner Reference Data"
        ]
      }
    },
    "/v1/webhooks/deliveries": {
      "get": {
        "description": "Paginated ledger of outbound webhook deliveries for this partner. Each row shows status (`pending`, `delivered`, `dead`), attempt count, and last error. Default retry policy: up to **6 delivery attempts** (1 initial + 5 retries) before `dead`.",
        "operationId": "list_webhook_deliveries_v1_webhooks_deliveries_get",
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 20,
              "title": "Limit",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Cursor"
            }
          },
          {
            "description": "Partner tenant identifier from onboarding (e.g. tnt_aiviue_aicolegion). Required on all protected resource routes.",
            "in": "header",
            "name": "X-Tenant-ID",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "OAuth2ClientCredentials": [],
            "TenantHeader": []
          }
        ],
        "summary": "List webhook deliveries",
        "tags": [
          "Partner Webhooks"
        ]
      }
    },
    "/v1/webhooks/deliveries/{delivery_id}/replay": {
      "post": {
        "description": "Manually resend a prior delivery within the **30-day** replay window. The HTTP body uses the **same `idempotencyKey`** as the original event — partners must deduplicate on that field to avoid duplicate processing.",
        "operationId": "replay_webhook_delivery_v1_webhooks_deliveries__delivery_id__replay_post",
        "parameters": [
          {
            "in": "path",
            "name": "delivery_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "title": "Delivery Id",
              "type": "string"
            }
          },
          {
            "description": "Unique key per logical write. Reuse with the same body returns the cached response; reuse with a different body returns 409 IDEMPOTENCY_CONFLICT.",
            "in": "header",
            "name": "X-Idempotency-Key",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          },
          {
            "description": "Partner tenant identifier from onboarding (e.g. tnt_aiviue_aicolegion). Required on all protected resource routes.",
            "in": "header",
            "name": "X-Tenant-ID",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "OAuth2ClientCredentials": [],
            "TenantHeader": []
          }
        ],
        "summary": "Replay a webhook delivery",
        "tags": [
          "Partner Webhooks"
        ]
      }
    },
    "/v1/webhooks/subscriptions": {
      "get": {
        "description": "Returns all active `event_type` + `url` pairs for your partner account. Scope: `webhooks:read`.",
        "operationId": "list_webhook_subscriptions_v1_webhooks_subscriptions_get",
        "parameters": [
          {
            "description": "Partner tenant identifier from onboarding (e.g. tnt_aiviue_aicolegion). Required on all protected resource routes.",
            "in": "header",
            "name": "X-Tenant-ID",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          }
        },
        "security": [
          {
            "OAuth2ClientCredentials": [],
            "TenantHeader": []
          }
        ],
        "summary": "List active webhook subscriptions",
        "tags": [
          "Partner Webhooks"
        ]
      },
      "post": {
        "description": "Register an HTTPS URL to receive **one** event type. Create multiple subscriptions (same or different URLs) for multiple events. Requires scope `webhooks:write` and `X-Idempotency-Key`.\n\n### Subscribable webhook events\n\nRegister **one `event_type` per** `POST /v1/webhooks/subscriptions` call. Use the same HTTPS URL for multiple events by creating multiple subscriptions.\n\nAlternative: set per-job `callback_urls` on `POST /v1/jobs` (see callback key column).\n\n| `event_type` | Phase | When fired | `callback_urls` key |\n|--------------|-------|------------|---------------------|\n| `creative.ready` | Job orchestration | A job poster/creative asset was generated and auto-published (per locale). | `creative_ready` |\n| `screening.ready` | Job orchestration | WhatsApp/chat screening questions are generated and published for the job. | `candidate_update` |\n| `voice.ready` | Job orchestration | Voice interview questions are generated and saved on the job. | `candidate_update` |\n| `campaign.live` | Job orchestration | The job campaign is published live (core pipeline complete). | `creative_ready` |\n| `distribution.started` | Distribution | Meta lead-ad distribution started successfully after campaign is live. | `analytics_update` |\n| `candidate.created` | Candidate funnel | A new candidate applied to a partner job (new application). | `candidate_update` |\n| `candidate.updated` | Candidate funnel | An existing application status or profile projection changed. | `candidate_update` |\n| `screening.started` | Candidate funnel | The candidate started screening for a job (chat or AI voice). | `candidate_update` |\n| `screening.completed` | Candidate funnel | The candidate finished screening (chat or AI voice). | `candidate_update` |\n| `interview.scheduled` | Candidate funnel | An AI voice interview was scheduled or outbound dial initiated. | `candidate_update` |\n| `interview.completed` | Candidate funnel | The AI voice interview finished (transcript saved). | `candidate_update` |\n| `grading.completed` | Candidate funnel | AI scores are finalized for an application (fit, intent, etc.). | `grading_update` |\n| `campaign.analytics.updated` | Campaign lifecycle | Campaign or offer-funnel analytics were updated (partner-reported or aggregated). | `analytics_update` |\n| `campaign.paused` | Campaign lifecycle | The job/campaign was paused via partner status API or platform action. | — |\n| `campaign.closed` | Campaign lifecycle | The job/campaign was closed. | — |\n\n**Scope:** `webhooks:write` to create/delete subscriptions; `webhooks:read` to list subscriptions and deliveries.\n\n**Also available:** `GET /v1/reference-data` returns `webhook_subscribable_event_types` and `webhook_events` (full catalog with descriptions).",
        "operationId": "create_webhook_subscription_v1_webhooks_subscriptions_post",
        "parameters": [
          {
            "description": "Unique key per logical write. Reuse with the same body returns the cached response; reuse with a different body returns 409 IDEMPOTENCY_CONFLICT.",
            "in": "header",
            "name": "X-Idempotency-Key",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          },
          {
            "description": "Partner tenant identifier from onboarding (e.g. tnt_aiviue_aicolegion). Required on all protected resource routes.",
            "in": "header",
            "name": "X-Tenant-ID",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PartnerWebhookSubscriptionCreateRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "OAuth2ClientCredentials": [],
            "TenantHeader": []
          }
        ],
        "summary": "Subscribe to a webhook event",
        "tags": [
          "Partner Webhooks"
        ]
      }
    },
    "/v1/webhooks/subscriptions/{subscription_id}": {
      "delete": {
        "operationId": "delete_webhook_subscription_v1_webhooks_subscriptions__subscription_id__delete",
        "parameters": [
          {
            "in": "path",
            "name": "subscription_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "title": "Subscription Id",
              "type": "string"
            }
          },
          {
            "description": "Unique key per logical write. Reuse with the same body returns the cached response; reuse with a different body returns 409 IDEMPOTENCY_CONFLICT.",
            "in": "header",
            "name": "X-Idempotency-Key",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          },
          {
            "description": "Partner tenant identifier from onboarding (e.g. tnt_aiviue_aicolegion). Required on all protected resource routes.",
            "in": "header",
            "name": "X-Tenant-ID",
            "required": true,
            "schema": {
              "minLength": 1,
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "OAuth2ClientCredentials": [],
            "TenantHeader": []
          }
        ],
        "summary": "Delete Webhook Subscription",
        "tags": [
          "Partner Webhooks"
        ]
      }
    }
  },
  "servers": [
    {
      "description": "Partner API",
      "url": "https://api.aiviue.com"
    }
  ]
}