API Reference

Complete reference for all Recruitsome API endpoints. Each entry links to its full article with examples and response bodies.

Base URL

Code

https://app.recruitsome.com/api/v1

Authentication

All endpoints require Bearer token authentication:

Code

Authorization: Bearer YOUR_API_KEY

Every endpoint (except the health check) also requires a specific scope on your API key — listed per endpoint below. A key without the scope gets a 403 with the INSUFFICIENT_SCOPE error code.

Endpoints

Health Check

GET/health

Verify API authentication and tenant context

Scope: none — any valid API key

Response:

JSON

{
  "status": "authenticated",
  "tenant": "tenant-id"
}

List Published Vacancies

GET/vacancies

Retrieve a paginated list of published vacancies

Scope: vacancies:read

Query Parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number
`per_page`	integer	20	Items per page (max: 100)
`language`	string	-	Filter by language code
`location_id`	integer	-	Filter by location ID
`department_id`	integer	-	Filter by department ID
`company_location_id[]`	array	-	Filter by company location IDs
`search`	string	-	Search in title and summary
`job_types[]`	array	-	Filter by job type IDs
`experience_levels[]`	array	-	Filter by experience level IDs
`education_levels[]`	array	-	Filter by education level IDs
`tags[]`	array	-	Filter by tag IDs (main tags cascade to include sub-tags)
`sort`	string	published_at	Sort field: `published_at`, `title`, `created_at`
`sort_direction`	string	desc	Sort direction: `asc` or `desc`
`include`	string	-	Include additional data: `facets`
`include_media`	boolean	false	Include header image URLs
`include_compensation`	boolean	false	Include compensation data
`include_company_name`	boolean	false	Include the company name

Response: Paginated list of vacancies — see List Published Vacancies

Get Vacancy Facets

GET/vacancies/facets

Get filter facets with counts for vacancy publications

Scope: vacancies:read

Query Parameters: Same filter parameters as List Vacancies (applied before counting)

Response: Facet counts for locations, departments, job types, experience levels, education levels, tags, and languages — see Get Vacancy Facets

Get Vacancy Details

GET/vacancies/{slug}

Retrieve complete information for a specific vacancy

Scope: vacancies:read

Path Parameters:

Parameter	Type	Required	Description
`slug`	string	Yes	URL-friendly vacancy identifier

Query Parameters:

Parameter	Type	Default	Description
`language`	string	-	Set response locale for translated labels
`include_compensation`	boolean	false	Include compensation data
`include_media`	boolean	false	Include header image URLs
`include_company_name`	boolean	false	Include the company name

Response: Complete vacancy details including full content — see Get Vacancy Details

Report Vacancy URL

POST/vacancies/{slug}/canonical-url

Report the canonical public URL your website assigned to a vacancy

Scope: vacancies:write

Path Parameters:

Parameter	Type	Required	Description
`slug`	string	Yes	The vacancy's `publication_slug`

Body:

Field	Type	Required	Description
`url`	string	Yes	The full canonical URL on your website. Must be `https://` (max 2048 chars) and on your career website domain

Response: Confirmation with the stored URL. Reported URLs take precedence over the configured URL pattern — see Report Vacancy URL

Submit Application

POST/applications

Submit a job application for a published vacancy

Scope: applications:write — limited to 10 requests per minute

Body:

Field	Type	Required	Description
`vacancy`	string or integer	Yes	The vacancy slug or ID
`candidate`	object	Yes	Candidate details: `given_name`, `family_name`, and `email` are required; `linkedin_url`, `mobile_phone`, and `fixed_phone` are optional
`documents`	object	No	Optional `resume`, `cover_letter`, and up to 5 `additional` documents (base64 encoded)
`privacy_policy_accepted`	boolean	No	Whether the candidate accepted your privacy policy
`tracking`	object	No	Optional `ip_address`, `user_agent`, and `referrer`

Response: 201 with the created application — see Submit Application

List Locations

GET/locations

Retrieve a paginated list of office locations

Scope: locations:read

Query Parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number
`per_page`	integer	20	Items per page (max: 100)
`language`	string	-	Set response locale for country names
`country_code`	string	-	Filter by country code
`search`	string	-	Search in name, city, and address
`sort`	string	name	Sort field: `name`, `locality`, `created_at`
`sort_direction`	string	asc	Sort direction: `asc` or `desc`
`include_coordinates`	boolean	false	Include latitude/longitude
`include_vacancy_count`	boolean	false	Include vacancy count

Response: Paginated list of locations with addresses — see List Locations

Get Location Details

GET/locations/{slug}

Retrieve complete information for a specific location

Scope: locations:read

Path Parameters:

Parameter	Type	Required	Description
`slug`	string	Yes	URL-friendly location identifier

Query Parameters:

Parameter	Type	Default	Description
`language`	string	-	Set response locale for country names
`include_coordinates`	boolean	false	Include latitude/longitude
`include_vacancy_count`	boolean	false	Include vacancy count

Response: Complete location details — see Get Location Details

List Team Members

GET/team

Retrieve a paginated list of employed team members

Scope: team:read

Query Parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number
`per_page`	integer	20	Items per page (max: 100)
`search`	string	-	Search in name, email, job title
`job_title`	string	-	Filter by job title
`role`	string	-	Filter by role name
`has_avatar`	boolean	false	Only members with avatars
`sort`	string	given_name	Sort field: `given_name`, `family_name`, `job_title`
`sort_direction`	string	asc	Sort direction: `asc` or `desc`
`include_phone`	boolean	false	Include phone number
`include_role`	boolean	false	Include role label

Response: Paginated list of team members with avatars — see List Team Members

Get Team Member Details

GET/team/{id}

Retrieve complete information for a specific team member

Scope: team:read

Path Parameters:

Parameter	Type	Required	Description
`id`	integer	Yes	Team member ID

Query Parameters:

Parameter	Type	Default	Description
`include_phone`	boolean	false	Include phone number
`include_role`	boolean	false	Include role label

Response: Complete team member details — see Get Team Member Details

List Candidates

GET/candidates

Retrieve a paginated list of candidates associated with a user

Scope: candidates:read

Query Parameters:

Parameter	Type	Default	Description
`user_id`	integer	required	Only candidates associated with this user are returned
`email`	string	-	Filter by email (exact match)
`search`	string	-	Search in first name, last name, and email
`status`	string	-	Filter by candidate status
`sort`	string	created_at	Sort field: `created_at`, `first_name`, `last_name`, `email`
`sort_direction`	string	desc	Sort direction: `asc` or `desc`
`per_page`	integer	20	Items per page (max: 100)

Response: Paginated list of candidates — see List Candidates

Create Candidate

POST/candidates

Create a candidate via resume upload (asynchronous)

Scope: candidates:write — limited to 10 requests per minute

Body:

Field	Type	Required	Description
`user_id`	integer	Yes	The user to associate the candidate with
`resume`	object	Yes	The resume: `filename`, `content` (base64 encoded), and `mime_type` (PDF, DOC, or DOCX, max 10MB)
`create_intake`	boolean	No	Also create an intake for the candidate

Response: 202 with a processing_id — the candidate is created in the background from the resume. See Create Candidate

List Articles

GET/articles

Retrieve a paginated list of published articles

Scope: articles:read

Query Parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number
`per_page`	integer	20	Items per page (max: 100)
`language`	string	-	Filter by language code
`type`	string	-	Filter by type: `news`, `company_update`, `event`, `blog_post`
`search`	string	-	Search in title and excerpt
`tags[]`	array	-	Filter by tag IDs (main tags cascade to include sub-tags)
`is_featured`	boolean	-	Filter featured articles only
`sort`	string	published_at	Sort field: `published_at`, `title`, `created_at`, `views_count`
`sort_direction`	string	desc	Sort direction: `asc` or `desc`
`include_media`	boolean	false	Include featured image URLs

Response: Paginated list of articles — see List Articles

Get Article Details

GET/articles/{slug}

Retrieve complete information for a specific article

Scope: articles:read

Path Parameters:

Parameter	Type	Required	Description
`slug`	string	Yes	URL-friendly article content identifier

Query Parameters:

Parameter	Type	Default	Description
`language`	string	-	Set response locale
`include_media`	boolean	false	Include featured image URLs

Response: Complete article details including full body HTML and SEO metadata — see Get Article Details

Status Codes

Code	Description
200	Success
201	Created (application submitted)
202	Accepted (candidate resume queued for processing)
400	Bad Request (business rule failed, e.g. vacancy closed)
401	Unauthorized
403	Forbidden (missing scope)
404	Not Found
422	Validation Error
429	Rate Limited
500	Server Error

Rate Limits

POST /vacancies/{slug}/canonical-url: 60 requests per minute per API key
POST /applications and POST /candidates: 10 requests per minute per API key
Read endpoints have no fixed per-key limit today — keep your request rate modest; limits may be introduced later
Rate-limited endpoints include X-RateLimit-Limit and X-RateLimit-Remaining headers in their responses

Support

Questions? Email us at [email protected], or browse the rest of the Help Center.

Base URL

Authentication

Endpoints

Health Check

List Published Vacancies

Get Vacancy Facets

Get Vacancy Details

Report Vacancy URL

Submit Application

List Locations

Get Location Details

List Team Members

Get Team Member Details

List Candidates

Create Candidate

List Articles

Get Article Details

Status Codes

Rate Limits

Support

Lees ook