Candidate data model

Updated:

View field support, webhooks, and list parameters for each integration on the Supported Integrations page.

FieldTypeRequiredDescription
idstringNo
created_atstring (date-time)No(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
updated_atstring (date-time)No(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
namestringNoThe candidate's full name
first_namestringNo
last_namestringNo
emailsAtsEmail[]NoThe candidate's email addresses
emails[].namestringNo
emails[].emailstringYes
emails[].typeenumNoValues: WORK, HOME, OTHER
titlestringNoCandidate’s current job title
telephonesAtsTelephone[]No
telephones[].telephonestringYes
telephones[].typeenumNoValues: WORK, HOME, OTHER, FAX, MOBILE
company_namestringNoName of company where candidate currently works
image_urlstringNo
tagsstring[]No
addressobjectNo
address.address1stringNo
address.address2stringNo
address.citystringNo
address.regionstringNoRegional area of the employee's address. For example, in the U.S., the region is the employee's state; in Canada, the region is the employee’s province.
address.region_codestringNoShort form for the regional area of the employee's address. For example, in the U.S., the region code is the two-letter abbreviation for the employee’s state; in Canada, the region is the two-letter abbreviation for the employee's province.
address.postal_codestringNo
address.countrystringNo
address.country_codestringNoCountry code for the country, in ISO 3166 A-2 format
external_identifierstringNo
link_urlsstring[]NoURLs for web pages containing additional material about the candidate (LinkedIn, other social media, articles, etc.)
originenumNoValues: AGENCY, APPLIED, INTERNAL, REFERRED, SOURCED, UNIVERSITY
company_idstringNo(reference to AtsCompany)
sourcesstring[]No
date_of_birthstring (date-time)No
user_idstringNoEmployee ID that owns the relationship for this candidate (reference to HrisEmployee)
user_idsstring[]Noreferences hris employees
web_urlstringNo
experiencesAtsCandidateExperience[]No
experiences[].company_namestringNo
experiences[].titlestringNo
experiences[].start_atstring (date-time)No(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
experiences[].end_atstring (date-time)No(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
educationAtsCandidateEducation[]No
education[].institutionstringNo
education[].levelstringNo
education[].degreestringNo
education[].field_of_studystringNo
education[].start_atstring (date-time)No(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
education[].end_atstring (date-time)No(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
skillsstring[]No
job_idsstring[]No
metadataAtsMetadata[]No
metadata[].idstringNoThe ID of the custom field definition (from the metadata/metadata endpoint).
metadata[].slugstringNoThe integration's API name (key) of an existing custom field. List valid slugs for this object with the metadata/metadata endpoint; unknown slugs are rejected by the integration.
metadata[].valueobjectNoThe field's value, typed by format: DATE as ISO-8601 (YYYY-MM-DD, or YYYY-MM-DDTHH:MM:SSZ for date-times); NUMBER, PRICE and CURRENCY as a number; BOOLEAN and YES_NO as true/false; MULTIPLE_SELECT as an array of option values; otherwise a string.
metadata[].namespacestringNo
metadata[].formatenumNoThe data type of the custom field, which determines how value is formatted. Values: TEXT, NUMBER, DATE, BOOLEAN, FILE, TEXTAREA, SINGLE_SELECT, MULTIPLE_SELECT, MEASUREMENT, PRICE, YES_NO, CURRENCY, URL
metadata[].extra_dataobjectNo
summarystringNoPersonal / professional bio
is_privatebooleanNoWhether the candidate is confidential / private (visible only to permitted users)
has_do_not_contactbooleanNoWhether the candidate must not be contacted for outreach

TypeScript

TypeScript
export type AtsCandidate = {
	id?: string;
	created_at?: string-time; // (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
	updated_at?: string-time; // (ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)
	name?: string; // The candidate's full name
	first_name?: string;
	last_name?: string;
	emails?: []; // The candidate's email addresses
	title?: string; // Candidate’s current job title
	telephones?: [];
	company_name?: string; // Name of company where candidate currently works
	image_url?: string;
	tags?: string[];
	address?: {
		address1?: string; 
		address2?: string; 
		city?: string; 
		region?: string; // Regional area of the employee's address.  For example, in the U.S., the region is the employee's state; in Canada, the region is the employee’s province. 
		region_code?: string; // Short form for the regional area of the employee's address.   For example, in the U.S., the region code is the two-letter abbreviation for the employee’s state; in Canada, the region is the two-letter abbreviation for the employee's province. 
		postal_code?: string; 
		country?: string; 
		country_code?: string; // Country code for the country, in ISO 3166 A-2 format 
	};
	external_identifier?: string;
	link_urls?: string[]; // URLs for web pages containing additional material about the candidate (LinkedIn, other social media, articles, etc.)
	origin?: 'AGENCY' | 'APPLIED' | 'INTERNAL' | 'REFERRED' | 'SOURCED' | 'UNIVERSITY';
	company_id?: string; // (reference to AtsCompany)
	sources?: string[];
	date_of_birth?: string-time;
	user_id?: string; // Employee ID that owns the relationship for this candidate (reference to HrisEmployee)
	user_ids?: string[]; // references hris employees
	web_url?: string;
	experiences?: [];
	education?: [];
	skills?: string[];
	job_ids?: string[];
	metadata?: [];
	summary?: string; // Personal / professional bio
	is_private?: boolean; // Whether the candidate is confidential / private (visible only to permitted users)
	has_do_not_contact?: boolean; // Whether the candidate must not be contacted for outreach
	raw?: any;
} 

Zod

Zod
import { z } from 'zod';

export const ZodAtsCandidate = z.object({
	id: z.string().optional(),
	created_at: z.string-time().optional().describe("(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"),
	updated_at: z.string-time().optional().describe("(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"),
	name: z.string().optional().describe("The candidate's full name"),
	first_name: z.string().optional(),
	last_name: z.string().optional(),
	emails: z.array().optional().describe("The candidate's email addresses"),
	title: z.string().optional().describe("Candidate’s current job title"),
	telephones: z.array().optional(),
	company_name: z.string().optional().describe("Name of company where candidate currently works"),
	image_url: z.string().optional(),
	tags: z.array().optional(),
	address: z.object({
			address1: z.string().optional(),
			address2: z.string().optional(),
			city: z.string().optional(),
			region: z.string().optional().describe("Regional area of the employee's address.  For example, in the U.S., the region is the employee's state; in Canada, the region is the employee’s province."),
			region_code: z.string().optional().describe("Short form for the regional area of the employee's address.   For example, in the U.S., the region code is the two-letter abbreviation for the employee’s state; in Canada, the region is the two-letter abbreviation for the employee's province."),
			postal_code: z.string().optional(),
			country: z.string().optional(),
			country_code: z.string().optional().describe("Country code for the country, in ISO 3166 A-2 format")
}).optional(),
	external_identifier: z.string().optional(),
	link_urls: z.array().optional().describe("URLs for web pages containing additional material about the candidate (LinkedIn, other social media, articles, etc.)"),
	origin: z.enum("AGENCY", "APPLIED", "INTERNAL", "REFERRED", "SOURCED", "UNIVERSITY").optional(),
	company_id: z.string().optional().describe("(reference to AtsCompany)"),
	sources: z.array().optional(),
	date_of_birth: z.string-time().optional(),
	user_id: z.string().optional().describe("Employee ID that owns the relationship for this candidate (reference to HrisEmployee)"),
	user_ids: z.array().optional().describe("references hris employees"),
	web_url: z.string().optional(),
	experiences: z.array().optional(),
	education: z.array().optional(),
	skills: z.array().optional(),
	job_ids: z.array().optional(),
	metadata: z.array().optional(),
	summary: z.string().optional().describe("Personal / professional bio"),
	is_private: z.boolean().optional().describe("Whether the candidate is confidential / private (visible only to permitted users)"),
	has_do_not_contact: z.boolean().optional().describe("Whether the candidate must not be contacted for outreach"),

});

Python

Python
import dataclasses

@dataclasses.dataclass
class AtsCandidateOrigin(str, Enum):
	AGENCY = 'AGENCY'
	APPLIED = 'APPLIED'
	INTERNAL = 'INTERNAL'
	REFERRED = 'REFERRED'
	SOURCED = 'SOURCED'
	UNIVERSITY = 'UNIVERSITY'

@dataclasses.dataclass
class PropertyAtsCandidateAddress:
	address1: Optional[str]
	address2: Optional[str]
	city: Optional[str]
	"""Regional area of the employee's address.  For example, in the U.S., the region is the employee's state; in Canada, the region is the employee’s province."""
	region: Optional[str]
	"""Short form for the regional area of the employee's address.   For example, in the U.S., the region code is the two-letter abbreviation for the employee’s state; in Canada, the region is the two-letter abbreviation for the employee's province."""
	region_code: Optional[str]
	postal_code: Optional[str]
	country: Optional[str]
	"""Country code for the country, in ISO 3166 A-2 format"""
	country_code: Optional[str]

@dataclasses.dataclass
class AtsCandidate:
	id: Optional[str]
	"""(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"""
	created_at: Optional[str]
	"""(ISO-8601 / YYYY-MM-DDTHH:MM:SSZ format)"""
	updated_at: Optional[str]
	"""The candidate's full name"""
	name: Optional[str]
	first_name: Optional[str]
	last_name: Optional[str]
	"""The candidate's email addresses"""
	emails: Optional[PropertyAtsCandidateEmails]
	"""Candidate’s current job title"""
	title: Optional[str]
	telephones: Optional[PropertyAtsCandidateTelephones]
	"""Name of company where candidate currently works"""
	company_name: Optional[str]
	image_url: Optional[str]
	tags: Optional[List[List[str]]]
	address: Optional[PropertyAtsCandidateAddress]
	external_identifier: Optional[str]
	"""URLs for web pages containing additional material about the candidate (LinkedIn, other social media, articles, etc.)"""
	link_urls: Optional[List[List[str]]]
	origin: Optional[AtsCandidateOrigin]
	"""(reference to AtsCompany)"""
	company_id: Optional[str]
	sources: Optional[List[List[str]]]
	date_of_birth: Optional[str]
	"""Employee ID that owns the relationship for this candidate (reference to HrisEmployee)"""
	user_id: Optional[str]
	"""references hris employees"""
	user_ids: Optional[List[List[str]]]
	web_url: Optional[str]
	experiences: Optional[PropertyAtsCandidateExperiences]
	education: Optional[PropertyAtsCandidateEducation]
	skills: Optional[List[List[str]]]
	job_ids: Optional[List[List[str]]]
	metadata: Optional[PropertyAtsCandidateMetadata]
	"""Personal / professional bio"""
	summary: Optional[str]
	"""Whether the candidate is confidential / private (visible only to permitted users)"""
	is_private: Optional[bool]
	"""Whether the candidate must not be contacted for outreach"""
	has_do_not_contact: Optional[bool]
Are we missing anything? Let us know
Was this page helpful?