Recruitment

Base URL: /api/v1/recruitment

Auth required: Yes (auth:api) for all endpoints.

The Recruitment module manages candidates, job openings, interviews, contracts, and employer details for internal HR and staffing use cases.

---

Candidates

Base URL: /api/v1/recruitment/candidates

Model Properties

Property	Type	Required	Description
id	integer	auto	Unique identifier
civility	string	No	Civility (e.g. M., Mme). Resolved from a lookup on read
first_name	string	No	First name
last_name	string	No	Last name
email_address	string	No	Primary email address
phone	string	No	Phone number
mobile_phone	string	No	Mobile phone number
email	string	No	Secondary email
postal_code	string	No	Postal code
dob	date	No	Date of birth
ssn	string	No	Social Security Number
ssn_special	boolean	No	Whether SSN is in a special format
id_expiry	date	No	ID document expiry date
date_of_entry	date	No	Date the candidate entered the system
number_of_children	integer	No	Number of children
active	boolean	No	Whether the candidate is active
has_picture	boolean	auto	Whether a profile picture is stored
has_docs	boolean	auto	Whether documents are attached
marital_status_id	integer	No	FK to marital statuses
married_to_candidate_id	integer	No	FK to another candidate (spouse in the system)
created_at	datetime	auto	Creation timestamp
updated_at	datetime	auto	Last update timestamp

Read-only computed fields (returned in responses):

Property	Type	Description
full_name	string	Formatted full name (civility + first/last name)
age	integer	Computed age from dob
picture_url	string	URL to the candidate's profile picture (if any)

Relations returned in responses: specialities, languages

---

GET /v1/recruitment/candidates

List candidates with pagination and sorting.

Query parameters:

Parameter	Type	Description
nb	integer	Items per page
sort	string	Sort field
direction	string	Sort direction (asc / desc)

Response 200: Paginated list of candidate objects.

---

GET /v1/recruitment/candidates/search

Search candidates by quick-search term.

Query parameters:

Parameter	Type	Required	Description
term	string	Yes	Search term

Response 200: Array of matching candidates.

---

POST /v1/recruitment/candidates

Create a candidate.

Body (JSON): Candidate attributes. Supports specialities (array of IDs), languages (array of IDs), filters (array of IDs), and married_to_candidate_id (sets up a bidirectional spouse link). Date fields (dob, id_expiry, date_of_entry) accept Y-m-d format.

Response 201: Created candidate object.

---

GET /v1/recruitment/candidates/{id}

Show a candidate with specialities, languages, marital status, candidate details, and contracts.

Response 200: Candidate object. Response 404: Not found.

---

PUT /v1/recruitment/candidates/{id}

Update a candidate. Supports the same relation fields as create.

Response 200: Updated candidate object. Response 404: Not found.

---

DELETE /v1/recruitment/candidates/{id}

Delete a candidate.

Response 200: Success. Response 404: Not found.

---

Candidate Queries

Base URL: /api/v1/recruitment/candidate-queries

Advanced candidate filtering using QueryBuilder with custom scopes.

GET /v1/recruitment/candidate-queries

Query candidates with advanced filters.

Query parameters (filters):

Parameter	Type	Description
filter[speciality_id]	integer	Filter by speciality
filter[available_in_country]	boolean	Available for in-country assignments
filter[available_abroad]	boolean	Available for international assignments
filter[available_housed]	boolean	Available to be housed on-site
filter[available_on]	date	Available on a specific date
filter[recruitment_filter_id]	integer	Filter by recruitment filter ID

Response 200: Filtered array of candidate objects.

---

Candidate Pictures

Base URL: /api/v1/recruitment/candidate-pictures

Endpoint	Method	Description
/v1/recruitment/candidate-pictures?candidate_id={id}	GET	Get picture status and URL for a candidate
/v1/recruitment/candidate-pictures	POST	Upload and process a profile picture for a candidate
/v1/recruitment/candidate-pictures?candidate_id={id}	DELETE	Delete a candidate's profile picture

POST body: Multipart form with candidate_id and the image file.

---

Candidate Resumes

Base URL: /api/v1/recruitment/candidate-resumes

Endpoint	Method	Description
/v1/recruitment/candidate-resumes?candidate_id={id}	GET	Stream the candidate's PDF resume
/v1/recruitment/candidate-resumes	POST	Generate a resume from template for a candidate
/v1/recruitment/candidate-resumes/mail-to	POST	Send the candidate's resume by email (truncated format)

GET query parameters:

Parameter	Type	Description
candidate_id	integer	Candidate ID
truncated	boolean	If true, return a truncated/anonymised version

POST /mail-to body (JSON):

Field	Type	Required	Description
candidate_id	integer	Yes	Candidate ID
email	string	Yes	Recipient email address

---

Candidate Details

Base URL: /api/v1/recruitment/candidate-details

Extended candidate information. Only one detail record is allowed per candidate.

Endpoint	Method	Description
/v1/recruitment/candidate-details	GET	List candidate detail records
/v1/recruitment/candidate-details	POST	Create a detail record (one per candidate)
/v1/recruitment/candidate-details/{id}	GET	Show a detail record
/v1/recruitment/candidate-details/{id}	PUT	Update a detail record
/v1/recruitment/candidate-details/{id}	DELETE	Delete a detail record

---

Employer Details

Base URL: /api/v1/recruitment/employer-details

Extended information for customer-employers. Only one detail record is allowed per customer.

Endpoint	Method	Description
/v1/recruitment/employer-details	GET	List employer detail records
/v1/recruitment/employer-details	POST	Create a detail record (one per customer)
/v1/recruitment/employer-details/{id}	GET	Show a detail record
/v1/recruitment/employer-details/{id}	PUT	Update a detail record
/v1/recruitment/employer-details/{id}	DELETE	Delete a detail record

---

Family Members

Base URL: /api/v1/recruitment/family-members

Family members linked to employer details.

Endpoint	Method	Description
/v1/recruitment/family-members	GET	List family members (filterable by ?employer_detail_id=, ordered by name)
/v1/recruitment/family-members	POST	Create a family member
/v1/recruitment/family-members/{id}	GET	Show a family member
/v1/recruitment/family-members/{id}	PUT	Update a family member
/v1/recruitment/family-members/{id}	DELETE	Delete a family member

---

Specialities

Base URL: /api/v1/recruitment/specialities

Job specialities used to classify candidates and recruitment positions.

Endpoint	Method	Description
/v1/recruitment/specialities	GET	List all specialities (ordered by name)
/v1/recruitment/specialities	POST	Create a speciality
/v1/recruitment/specialities/{id}	GET	Show a speciality
/v1/recruitment/specialities/{id}	PUT	Update a speciality
/v1/recruitment/specialities/{id}	DELETE	Delete a speciality

---

Recruitment Filters

Base URL: /api/v1/recruitment/recruitment-filters

Reusable filter presets used to tag and query candidates and recruitments.

Endpoint	Method	Description
/v1/recruitment/recruitment-filters	GET	List all filters (ordered by name)
/v1/recruitment/recruitment-filters	POST	Create a filter
/v1/recruitment/recruitment-filters/{id}	GET	Show a filter
/v1/recruitment/recruitment-filters/{id}	PUT	Update a filter
/v1/recruitment/recruitment-filters/{id}	DELETE	Delete a filter

---

Recruitments (Job Openings)

Base URL: /api/v1/recruitment/recruitments

Recruitment records represent job openings or staffing needs.

Endpoint	Method	Description
/v1/recruitment/recruitments	GET	List recruitments (with related data)
/v1/recruitment/recruitments	POST	Create a recruitment position
/v1/recruitment/recruitments/{id}	GET	Show a recruitment
/v1/recruitment/recruitments/{id}	PUT	Update a recruitment
/v1/recruitment/recruitments/{id}	DELETE	Delete a recruitment

Supports languages, filters, speciality_id in the request body. The start date field accepts Y-m-d format.

---

Recruitment Interviews

Base URL: /api/v1/recruitment/interviews

GET /v1/recruitment/interviews/statuses

Get the list of available interview statuses.

Response 200: Array of status strings.

GET /v1/recruitment/interviews

List interviews.

Query parameters:

Parameter	Type	Description
recruitment_id	integer	Filter by recruitment
candidate_id	integer	Filter by candidate
customer_id	integer	Filter by customer

Response 200: Array of interview objects with related recruitment and customer data.

Standard CRUD: /v1/recruitment/interviews[/{id}]

Endpoint	Method	Description
/v1/recruitment/interviews	POST	Create an interview
/v1/recruitment/interviews/{id}	GET	Show an interview
/v1/recruitment/interviews/{id}	PUT	Update an interview
/v1/recruitment/interviews/{id}	DELETE	Delete an interview

Date fields interviewed_at and sent_resume_at accept Y-m-d H:i:s format.

---

Recruitment Contracts

Base URL: /api/v1/recruitment/contracts

Contracts formalise the placement of a candidate with an employer.

Endpoint	Method	Description
/v1/recruitment/contracts	GET	List contracts (filterable by ?customer_id= or ?candidate_id=)
/v1/recruitment/contracts	POST	Create a contract
/v1/recruitment/contracts/{id}	GET	Show a contract with specialities
/v1/recruitment/contracts/{id}	PUT	Update a contract
/v1/recruitment/contracts/{id}	DELETE	Delete a contract

start and end date fields accept Y-m-d format. Supports specialities (array of IDs).

---

Recruitment Exports

Base URL: /api/v1/recruitment/exports

Endpoint	Method	Description
/v1/recruitment/exports	GET	List available export types (e.g. candidates, customers)
/v1/recruitment/exports/{type}	GET	Download an Excel export of the specified type