API Field Directory - CandidatesFields available via the API for Candidate records, with required formatting.
Field Name
Format
Example
Description
UserId *
String
"USER_10"
The Colleague 7 User ID (mandatory)
Forenames *
String
"John"
The forenames of the Candidate
Surname *
String
"Smith"
The surname of the Candidate
KnownAs
String
"John"
The Known As / Salutation field
Title
String/Lookup
"Mr" or lookup code
The lookup description or code of Title
DirectNumber
String
"01603 735935"
Direct telephone number of the Candidate
DirectFax
String
"01603 735935"
Direct fax number (if applicable)
MobileNumber
String
"07777 777777"
Mobile number of the Candidate
OtherNumber
String
"01603 735935"
Another relevant phone number
EmailAddress
String
"support@colleaguesoftware.com"
Email address of the Candidate
EmailAddress2
String
"sales@colleaguesoftware.com"
Secondary email address
Website
String
"http://www.colleaguesoftware.com"
A website address specific to the Candidate
Gender
String/Lookup
"Male" or lookup code
Gender lookup description or code
Married
Boolean
"true"
Married flag
CandidateStatus
String/Lookup
"Active" or lookup code
Candidate Status lookup
CandidateType
String/Lookup
"Contract" or lookup code
Candidate Type lookup
CandidateSource
String/Lookup
"Referral" or lookup code
Candidate Source lookup
Nationality
String/Lookup
"British" or lookup code
Nationality lookup
JobType
String
"Project Manager"
Freetext preferred job titles
DateOfBirth
date-time (dd MMM yyyy)
"02 Jul 1981"
Candidate date of birth
DateAvailable
date-time (dd MMM yyyy)
"28 Jan 2020"
Next available date
CurrentSalary
int32
"30000"
The current salary
WantedSalary
int32
"35000"
The desired salary
CurrentPay
int32
"100"
The current pay rate
WantedPay
int32
"150"
The desired pay rate
NoticePeriod
int32
"4"
Notice period in weeks
SalaryBreakdown
String
"Company Car and Mobile Phone"
Freetext desired package
AddressLine1
String
"The Control Tower"
First line of address
AddressLine2
String
"Witchcraft Way"
Second line of address
AddressLine3
String
"Rackheath"
Third line of address
City
String
"Norwich"
Town of address
County
String
"Norfolk"
County of address
Postcode
String
"NR13 6GA"
Postcode of address
Country
String/Lookup
"United Kingdom" or lookup code
Country of address
TelephoneNumber
String
"01603 735935"
Home telephone number
FaxNumber
String
"01603 735935"
Home fax number
NoteTab
int32
"0"
Note tab to add notes to (0–4)
Notes
String
"Only Available via Mobile"
Generic notes against the Candidate
CurrencyCode
String/Lookup
"GBP" or lookup code
Currency lookup
PreviousJobTitles
String
"Account Manager, Project Manager"
Freetext previous job titles
CustomFields
Array
JSON array of { customFieldName, customFieldValue }
Custom fields to add to the Candidate
SkillsToAdd
Array
JSON array of { lookupCode, lookupParent, lookupPath }
Skills to add (lookupCode mandatory; parent & path optional)
CandidateId
int32
"491"
Unique ID of the Candidate record
Address
String
"16 Vinnetrow Road Chichester West Sussex PO20 3RP"
Primary address as a single line
Searchname
String
"Smith-John"
Surname-forename search key
HMRCType
String/Lookup
"Limited Company"
HMRC employment type
CurrentandForwardContractors
Boolean (0/1)
"0"
Candidate is a current or forward contractor
PreviouslyPlaced
Boolean (0/1)
"0"
Candidate has previously been placed
OwnerId
int32
"491"
ID of the record owner
Age
int32
"45"
Age, calculated from date of birth
AddressType
int32
"0"
Address type code
AddressId
int32
"2333"
ID of the primary address
JobCode
String
"Account Manager"
Preferred job title
DateCreated
date-time
"2015-05-11 10:15:30.337"
Date the record was created
CreatedBy
String
"Daniel Woodsford"
User who created the record
DateAmended
date-time
"2026-09-28 10:39:00.000"
Date the record was last amended
AmendedBy
String
"David Demo"
User who last amended the record
NoteId
int32
"3259"
ID of the notes held against the record
AddressTypeDescription
String
null
Description of the address type
CountryDescription
String
"United Kingdom"
Country lookup description
AddressDateCreated
date-time
"2015-05-11 10:15:30.380"
Date the address was created
AddressCreatedBy
String
"Daniel Woodsford"
User who created the address
AddressDateAmended
date-time
"2026-03-24 13:27:01.287"
Date the address was last amended
AddressAmendedBy
String
"David Demo"
User who last amended the address
PrimaryFlag
Boolean (0/1)
"1"
Address is the primary address
AddressDesc
String
null
Address description
PostcodePrefix
String
"NR136GA"
Postcode with spaces removed
InvoiceAddress
Boolean (0/1)
"0"
Address is an invoice address
AddressTaxCode
String
null
Tax code held against the address
VatNumber
String
null
VAT number held against the address
CreditLimit
Decimal
"0.0"
Credit limit
InsuredCreditLimit
Decimal
"0.0"
Insured credit limit
ArchivedDate
date-time
null
Date the record was archived
LastContacted
date-time
"2026-07-13 13:57:00.000"
Date the Candidate was last contacted
CompanyRegistrationNo
String
"REGNO4567"
Company registration number
ContactId
int32
"149"
ID of the linked Contact record
RequiredPay
String
""
Freetext required pay
FormattedMobileNumber
String
"+447503047777"
Mobile number in international format
WantedPayEstimated
Boolean (0/1)
"0"
Wanted pay is an estimate
WantedSalaryEstimated
Boolean (0/1)
"0"
Wanted salary is an estimate
TaxCode
String
"20"
Tax code
MgmtCompanyId
int32
"0"
ID of the management company
PaymentMethod
String/Lookup
"BACS"
Payment method
BuildingSocietyReference
String
null
Building society reference
PayrollRef
String
"PAY REF 12357"
Payroll reference
LastContactedBy
String
"David Demo"
User who last contacted the Candidate
LastDocumentDate
date-time
"2026-07-09 10:05:59.383"
Date of the latest document
LtdCompany
String
"Example Ltd Company"
Limited company name
PreferredJobTitle
String
"Account Manager"
Preferred job title
ResourcerJobTitle
String
"Senior Test Analyst, C++ Developer"
Job titles recorded by the Resourcer
LtdCompanyId
int32
"0"
ID of the limited company
ResourcerStatus
int32
"0"
Resourcer status code
OwnedBy
String
"All Users, Brett Cole, Cam Horton"
Users who own the record
AllowSelfBilling
Boolean (0/1)
"0"
Self billing is allowed
EmailRemittanceAddress
String
null
Email address for remittance advice
NationalInsuranceNo
String
"JM642315B"
National Insurance number
FullName
String
"John Smith"
Forenames and surname
MmChargesPaidBy
int32
"0"
Who pays management company charges
DateOwned
date (dd MMM yyyy)
"11 May 2015"
Date the current ownership began
DefaultTimesheetStatus
int32
"0"
Default timesheet status code
MailshotStatus
String/Lookup
"Allow All"
Mailshot status
FormatedMobileNumber
String
"+447503047777"
Duplicate of FormattedMobileNumber
AuthorisationLevel
int32
"0"
Authorisation level
PaymentAddressId
int32
"2333"
ID of the payment address
PaymentContact
String
"John Smith"
Payment contact name
PaymentContactId
int32
"0"
ID of the payment contact
PaymentFrequency
String/Lookup
"Monthly"
Payment frequency
AlertText
String
""
Alert text shown on the record
PaymentPeriod
int32
"0"
Payment period code
DeletedBy
String
null
User who deleted the record
DeletedDate
date-time
null
Date the record was deleted
AccountReference
String
"ACCREF5566"
Account reference
LiveRequirements
int32
"0"
Number of live requirements
ForwardInterviews
int32
"0"
Number of upcoming interviews
FullContactXML
String
null
FullContact enrichment data
FullContactXMLLastUpdatedDate
date-time
null
Date the FullContact data was last updated
EntityDescription
String
"John Smith - Telephone: 07503 047777, Location: Chichester"
Summary description of the record
Email
String
"john.smith@colleaguesoftware.com support@colleaguesoftware.com"
All email addresses, space separated
Name
String
"John Smith"
Display name
FullNumbers
String
"~07503047777~01603736403~"
Phone numbers, tilde separated
ArchivedBy
String
null
User who archived the record
LatestDocumentId
int32
"7631"
ID of the latest document
VatNo
String
"VAT1234567"
VAT number
ConsentRequested
date-time
"2025-03-31 00:00:00.000"
Date GDPR consent was requested
ResponseReceived
date-time
"2025-11-07 10:59:00.000"
Date a GDPR consent response was received
ConsentGiven
Boolean (0/1)
"1"
GDPR consent has been given
GDPRConsentId
GUID
"7bf68719-ETC"
ID of the GDPR consent request
GDPRConsentUser
GUID
"5964f9d6-ETC"
User linked to the GDPR consent
AllNumbers
String
"~07503047777~01243629864"
All phone numbers, tilde separated
Alert
String
""
Alert flag text
AllEmailAddresses
String
"john.smith@colleaguesoftware.com support@colleaguesoftware.com"
All email addresses, space separated
CurrentEmployer
String
"Colleague Software"
Current employer
CurrentEmployerId
int32
"1"
ID of the current employer Company record
CurrentManager
String
"John Smith"
Current line manager
CurrentManagerId
int32
"149"
ID of the current manager Contact record
CurrentJobTitle
String
"Java Developer"
Current job title
CurrentSituationPlacementId
int32
"1108"
ID of the current situation placement
SkillCount
int32
"49"
Number of skills held against the Candidate
SecurityStamp
String
null
Portal security stamp
ImportedRecord
Boolean (0/1)
"0"
Record was created by an import
AllAddresses
String
"|22 John Street Moulton...|"
All addresses, pipe separated
PortalEmailAddress
String
null
Portal sign-in email address
PortalPIN
String
null
Portal PIN
PortalActiveUser
Boolean (0/1)
"0"
Candidate is an active Portal user
PortalUserId
String
null
Portal user ID
AddressLink
String
HTML link to Google Maps
Link to view the address location
NoticePeriodUOM
int32
"1"
Notice period unit of measure
IsMerged
Boolean (0/1)
"0"
Record has been merged
ExperienceStarted
date (dd MMM yyyy)
"07 Feb 2024"
Date experience started
YearsOfExperience
int32
"2"
Years of experience
UTR
String
null
Unique Taxpayer Reference
SocialSecurityNo
String
null
Social security number
MailshotExpiry
date-time
"2026-08-01 00:00:00.000"
Date the mailshot status expires
WhatExContactId
GUID
"8b5a7047-ETC"
WhatEx contact ID
Birthday
date-time
"1981-07-02 00:00:00.000"
Birthday (day and month only)
CandidateSummary
String
"John Smith is a resident of Chichester..."
Summary of the Candidate's profile
CurrentPayUOM
int32
"-1"
Current pay unit of measure
WantedPayUOM
int32
"-1"
Wanted pay unit of measure
* Mandatory field.
|