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

# Update Client Referral Status

`PATCH /api/client-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/client-referrals/{referral_id}/status`
- Auth: HTTP bearer

Update client referral status (founder or recruiter).

When status changes to "Signed" and the referral has a converted_company_id,
the reward is automatically calculated and applied as a Stripe customer
balance credit (auto-deducted from the next invoice).

## Path parameters

- `referral_id` string, required

## Request body

- ClientReferralUpdate: Update client referral (founder only)
  - `status` 'Submitted' | 'Qualified' | 'Contacted' | 'Demo_Scheduled' | 'Proposal_Sent' | 'Signed' | 'Lost' | 'Rejected', nullable
  - `qualification_notes` string, nullable: Founder notes
  - `assigned_to` string, nullable: User ID of founder handling this
  - `demo_date` string, nullable: Scheduled demo date (ISO format)
  - `signed_date` string, nullable: When deal closed (ISO format)
  - `lost_reason` string, nullable: Why we lost the deal
  - `converted_company_id` string, nullable: Created company record ID

## Response `200`

Successful Response

- ClientReferralResponse: Client referral details
  - `id` string, required: Record ID
  - `referral_type` 'Client' | 'Candidate', required
  - `referrer_name` string, required: Name of person who referred
  - `referrer_company` string, nullable: Referrer's company (if client)
  - `referred_company_name` string, required
  - `referred_contact_name` string, required
  - `referred_contact_email` string, required
  - `referred_contact_title` string, nullable
  - `referred_company_domain` string, required
  - `referred_company_size` string, required
  - `referred_industry` string, required
  - `estimated_pricing_tier` string, required
  - `referral_reason` string, nullable
  - `specific_need` string, nullable
  - `status` string, required
  - `qualification_score` integer, required: Qualification score 0-100
  - `qualification_notes` string, nullable
  - `assigned_to` string, nullable
  - `demo_date` string, nullable
  - `signed_date` string, nullable
  - `lost_reason` string, nullable
  - `converted_company_id` string, nullable
  - `reward_tier` string, nullable
  - `reward_amount` number, nullable
  - `reward_status` string, required
  - `reward_paid_date` string, date-time, nullable
  - `reward_payment_id` string, nullable
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, nullable
  - `estimated_reward` string, required: Display text like '$2,000'
  - `status_history` object[]: Status change history
  - `auto_reward` object, nullable: Auto-reward result when status changed to Signed

## 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)