---
title: "Submit Candidate Referral"
method: POST
path: "/api/candidate-referrals"
tags: ["candidate-referrals"]
---

# Submit Candidate Referral

`POST /api/candidate-referrals`

## 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`
- Auth: HTTP bearer

Submit a new candidate referral

Candidates and client users can submit referrals.
Automatically calculates quality score and checks for duplicates.

## Request body

- CandidateReferralCreate: Submit a new candidate referral
  - `referred_name` string, required: Full name of referred person
  - `referred_email` string, email, required: Email of referred person
  - `referred_linkedin_url` string, nullable: LinkedIn profile URL
  - `referred_github_url` string, nullable: GitHub profile URL
  - `referred_skills` string, nullable: Comma-separated skills
  - `referred_location` string, nullable: Country/city location
  - `referral_reason` string, nullable: Why they're a good fit
  - `relationship` 'Former Colleague' | 'Friend' | 'Mentor/Mentee' | 'Other', required: Relationship with referred person
  - `current_role` string, nullable: Current job title
  - `current_company` string, nullable: Current employer

## Response `201`

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)