API Reference

Complete reference for all RecruitSome API endpoints.

Base URL

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

Authentication

All endpoints require Bearer token authentication:

Authorization: Bearer YOUR_API_KEY

Endpoints

Health Check

Response:

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

---

List Published Vacancies

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
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

Response: Paginated list of vacancies

---

Get Vacancy Facets

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

---

Get Vacancy Details

Path Parameters:

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

Response: Complete vacancy details including full content

---

List Locations

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
sort_direction	string	asc	Sort direction
include_coordinates	boolean	false	Include latitude/longitude
include_vacancy_count	boolean	false	Include vacancy count

Response: Paginated list of locations with addresses

---

Get Location Details

Path Parameters:

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

Response: Complete location details

---

List Team Members

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
sort_direction	string	asc	Sort direction
include_phone	boolean	false	Include phone number
include_role	boolean	false	Include role label

Response: Paginated list of team members with avatars

---

Get Team Member Details

Path Parameters:

Parameter	Type	Required	Description
id	integer	Yes	Team member ID

Response: Complete team member details

---

List Articles

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

---

Get Article Details

Path Parameters:

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

Response: Complete article details including full body HTML and SEO metadata

---

Status Codes

Code	Description
200	Success
401	Unauthorized
403	Forbidden
404	Not Found
422	Validation Error
429	Rate Limited
500	Server Error

Rate Limits

• 60 requests per minute per API key
• Rate limit headers included in all responses

SDKs and Libraries

Official SDKs coming soon for:

• JavaScript/TypeScript
• Python
• PHP
• Ruby

Support

For API support and questions:

• Email: [email protected]
• Documentation: https://docs.recruitsome.com
• Status: https://status.recruitsome.com