DemandFlow Support Centre

CANDIDATE: Candidate

A recruitment overlay of PPL representing a person as a candidate in the hiring process.

Default definition. This article describes the default CANDIDATE definition shipped with DemandFlow. Administrators can add, remove, rename, or re-type fields, change which ones are required, and alter the layout from the Definitions screen in Settings. Your tenant's current schema may differ from what is shown here. To read the current definition at any time, GET the DEFINITION object whose id matches CANDIDATE.

Entity properties

Property	Value
Entity code	`CANDIDATE`
Display name	Candidate
Plural	Candidates
Level	230
Extends	`PPL`. See Entity Extension.

Use cases

CANDIDATE is a recruitment overlay of PPL, following the same 'extends' pattern as LEAD. PPL remains the canonical contact record; CANDIDATE captures recruitment-specific context (availability, notice period, salary expectations, right to work, preferred location, candidate status and source, recruiter ownership). A CANDIDATE always links back to a PPL via df_extendObject, and the same person can simultaneously be a LEAD, CANDIDATE and other overlays. INTERVIEW.candidate and VAC shortlist are re-pointed at CANDIDATE so recruitment activity targets the overlay rather than the raw PPL.

Fields

Because this entity extends PPL, some fields may actually be stored on the linked base record rather than on this record directly. See Entity Extension.

General: Candidate Details

Field	Type	Notes
`df_extendObject`	reference → `PPL`	Read-only. Canonical contact record. Click the arrow to open and edit.
`name`	relatedProperty	Full Name.
`nameFirst`	relatedProperty	First Name.
`nameLast`	relatedProperty	Last Name.
`email`	relatedProperty	Email.
`phone`	relatedProperty	Phone.
`phone2`	relatedProperty	Phone (2).
`job`	relatedProperty	Current Job Title.
`linkedin`	relatedProperty	LinkedIn.
`currentEmployer`	reference → `COM`	Current Employer.

General: Recruitment Pipeline

Field	Type	Notes
`recruiterOwner`	reference → user	Recruiter.
`candidateStatus`	enum	Status. Valid ids: `new` (New), `screening` (Screening), `qualified` (Qualified), `active` (Active), `submitted` (Submitted), `interviewing` (Interviewing), `offer` (Offer), `placed` (Placed), `onhold` (On Hold), `rejected` (Rejected), `withdrawn` (Withdrawn).
`candidateSource`	enum	Source. Valid ids: `inbound` (Inbound Application), `referral` (Referral), `jobBoard` (Job Board), `linkedin` (LinkedIn), `directApproach` (Direct Approach), `website` (Website), `event` (Event), `other` (Other).
`discipline`	reference → `DISCIPLINE`	Discipline.
`seniority`	enum	Seniority. Valid ids: `junior` (Junior), `mid` (Mid), `senior` (Senior), `lead` (Lead), `principal` (Principal), `director` (Director), `executive` (Executive).
`rejectedReason`	text (multi-line)	Rejected/Withdrawn Reason. Visible when `candidateStatus` = `rejected`.

General: Availability & Expectations

Field	Type	Notes
`availability`	enum	Availability. Valid ids: `immediate` (Immediate), `oneWeek` (1 Week), `twoWeeks` (2 Weeks), `oneMonth` (1 Month), `twoMonths` (2 Months), `threeMonths` (3 Months), `notLooking` (Not Looking).
`noticePeriod`	text	Notice Period. Placeholder: e.g. 3 months.
`availableFrom`	date	Available From.
`currentSalary`	number	Current Salary.
`salaryExpectation`	number	Salary Expectation.
`dayRateExpectation`	number	Day Rate Expectation.
`positionType`	enum	Position Type. Valid ids: `permanent` (Permanent), `contract` (Contract), `temporary` (Temporary), `either` (Either).
`preferredLocation`	text (multi-line)	e.g. London, remote, within 1 hour of M25
`willingToRelocate`	boolean	Willing to Relocate.
`rightToWork`	enum	Right to Work. Valid ids: `uk` (UK Citizen), `settled` (Settled Status), `visa` (Valid Visa), `sponsorship` (Requires Sponsorship), `unknown` (Unknown).

Attachments

Field	Panel	Allowed types	Max files
`cv`	CV & Documents	`pdf`, `doc`, `docx`	multiple
`candidateDocuments`	CV & Documents	`pdf`, `doc`, `docx`, `xls`, `xlsx`, `png`, `jpg`, `jpeg`, `msg`, `eml`	multiple

Relationships

Lookups: df_extendObject points at a PPL record; currentEmployer points at a COM record; discipline points at a DISCIPLINE record.
Extends: this entity extends PPL. See Entity Extension.
Related lists: BGCHECK (format SUB|CANDIDATE), INTERVIEW (via candidate).
Activity: activity timeline panel attached.

Creating a Candidate via the API

POST /v1/objects
Authorization: Bearer <your-pat>
Content-Type: application/json

{
  "entity":   "CANDIDATE",
  "level":    230,
  "comboKey": "SUB:<your-sub-id>|ENT:",
  "name": "Full Name",
  "candidateStatus": "new",
  "candidateSource": "inbound",
  "seniority": "junior"
}

Listing Candidates records

GET /v1/entities/CANDIDATE/SUB

DemandFlow Support Centre

CANDIDATE: Candidate

CANDIDATE: Candidate

Entity properties

Use cases

Fields

Attachments

Relationships

Creating a Candidate via the API

Listing Candidates records

See also

Was this article helpful?