Public API Reference (Beta)Applicants/CandidatesCore

Create an applicant

Creates a new applicant (candidate) linked to the authenticated user’s company. Required fields: firstName, lastName, email. Phones, education, employment history, notes, tags, social links, and resumes are not set here — add them afterward via their dedicated sub-resource endpoints (e.g. POST /api/v1/applicants/{guid}/phones).

Authentication

X-Brightmove-Company-ApiKeystring
BrightMove Company Api Key
X-Brightmove-User-ApiKeystring
BrightMove User Api Key

Request

This endpoint expects an object.
firstNamestringRequired
Applicant's first name.
lastNamestringRequired
Applicant's last name.
emailstringRequired
Applicant's personal email address.
middleNamestringOptional
Applicant's middle name or initial.
workEmailstringOptional
Applicant's work email address.
addressstringOptional
Street address line 1.
address2stringOptional

Street address line 2 (apartment, suite, etc.).

citystringOptional
City.
stateIdlongOptional

State ID from the BrightMove state lookup. Use GET /api/v1/lookup/states to retrieve valid IDs.

postalCodestringOptional
Postal code.
currentCompanystringOptional
Applicant's current or most recent employer.
currentTitlestringOptional
Applicant's current or most recent job title.
primarySkillsstringOptional

Comma-separated list of the applicant’s primary skills.

confidentialbooleanOptional

When true, marks this applicant as confidential. Viewing confidential applicants requires the VIEW_APPLICANT_CONFIDENTIAL permission.

emailAllowedbooleanOptional
When true, the applicant has opted in to email communications.
smsAllowedbooleanOptional

When true, the applicant has opted in to SMS/text message communications.

recruiterGuidstringOptional
GUID of the recruiter to assign to this applicant. Pass an empty string to remove the current assignment.
sourcestringOptional

Applicant source name exactly as configured for your company (e.g. ‘LinkedIn’, ‘Referral’). If omitted, the company default source is used.

sourceOtherstringOptional

Free-text detail when source is ‘Other’.

statusNotestringOptional
Internal comment about the current status.
dobstringOptional

Date of birth, in ISO-8601 format.

genderIdlongOptional

Gender. Use GET /api/v1/lookup/genders to retrieve valid IDs.

raceEthnicityIdlongOptional

Race/ethnicity. Use GET /api/v1/lookup/race-ethnicities to retrieve valid IDs.

veteranStatusIdlongOptional

Veteran status. Use GET /api/v1/lookup/veteran-statuses to retrieve valid IDs.

disabilityStatusIdlongOptional

Disability status. Use GET /api/v1/lookup/disability-statuses to retrieve valid IDs.

visaStatusIdlongOptional

Visa/work permit status. Use GET /api/v1/lookup/visa-statuses to retrieve valid IDs.

employmentTypeIdlongOptional

Preferred employment type. Use GET /api/v1/lookup/employment-types to retrieve valid IDs.

currentPaydoubleOptional
Applicant's current pay rate, if known.
currentPayTypeIdlongOptional

Rate type for currentPay. Use GET /api/v1/lookup/pay-types to retrieve valid IDs.

desiredPaydoubleOptional
Applicant's desired pay rate, if known.
desiredPayTypeIdlongOptional

Rate type for desiredPay. Use GET /api/v1/lookup/pay-types to retrieve valid IDs.

payCommentsstringOptional
Notes about the applicant's pay expectations.
doNotHirebooleanOptional
When true, this applicant should not be considered for hire.
currentEmployeebooleanOptional
When true, this applicant is a current employee.
availableDatestringOptional

Date the applicant becomes available to start, in ISO-8601 format.

availabilityCommentsstringOptional
Notes about the applicant's availability.
referredBystringOptional
Name of the person or source that referred this applicant.
preferredLocationstringOptional
Applicant's preferred work location.
rankintegerOptional

Numeric rank/priority assigned to this applicant.

vendorGuidstringOptional

GUID of the vendor (staffing partner/subcontractor) that submitted this applicant.

linkedContactGuidstringOptional

GUID of the client contact to link this applicant to (e.g. an internal employee referral).

Response

Applicant created successfully