---
title: "Update Referral Status"
method: PATCH
path: "/api/candidate-referrals/{referral_id}/status"
tags: ["candidate-referrals"]
---

# Update Referral Status

`PATCH /api/candidate-referrals/{referral_id}/status`

## Request

- Base URL: `https://api.ruzora.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.ruzora.com/api/candidate-referrals/{referral_id}/status`
- Auth: HTTP bearer

Update candidate referral status (founder or recruiter)

## Path parameters

- `referral_id` string, required

## Request body

- CandidateReferralUpdate: Update candidate referral (founder only)
  - `status` 'Submitted' | 'Under Review' | 'Qualified' | 'Contacted' | 'Screening' | 'Placed' | 'Rejected' | 'Lost' | 'Duplicate', nullable
  - `qualification_notes` string, nullable: Founder notes on qualification
  - `created_candidate_id` string, nullable: Candidate ID if converted
  - `matched_placement_id` string, nullable: Placement ID if placed
  - `reward_status` 'Pending' | 'Qualified' | 'Approved' | 'Paid' | 'Ineligible', nullable
  - `reward_amount` number, nullable: Reward amount in USD

## Response `200`

Successful Response

- CandidateReferralResponse: Candidate referral details
  - `id` string, required: Record ID
  - `referrer_type` string, required
  - `referrer_email` string, required
  - `referred_name` string, required
  - `referred_email` string, required
  - `referred_linkedin_url` string, nullable
  - `referred_github_url` string, nullable
  - `referred_skills` string, nullable
  - `referred_location` string, nullable
  - `referral_reason` string, nullable
  - `relationship` string, nullable
  - `current_role` string, nullable
  - `current_company` string, nullable
  - `status` string, required
  - `quality_score` integer, required: Quality score 0-100
  - `duplicate_of_candidate_id` string, nullable
  - `created_candidate_id` string, nullable
  - `matched_placement_id` string, nullable
  - `reward_status` string, required
  - `reward_amount` number, nullable
  - `reward_paid_date` string, date-time, nullable
  - `conversion_date` string, date-time, nullable
  - `created_at` string, date-time, required
  - `estimated_reward` string, required: Display text like '$500' or '10% off invoice'
  - `status_history` object[]: Status change audit trail
  - `auto_reward` object, nullable: Auto-reward result if triggered

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/ruzora/apis/ruzora-candidate-crm-api.md) · [All operations](https://skmtc.dev/ruzora/apis/ruzora-candidate-crm-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ruzora/apis/ruzora-candidate-crm-api/revisions/f9b8223f3ac4?raw)