RecruitSome API

The RecruitSome API provides programmatic access to published vacancy data, enabling seamless integration with your recruitment platforms, job boards, and HR systems.

Base URL

All API requests should be made to:

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

Authentication

The RecruitSome API uses Bearer token authentication. You'll need to include your API key in the Authorization header of every request.

Authorization: Bearer YOUR_API_KEY

Getting Started

1. Generate an API Key

To use the RecruitSome API, you first need to generate an API key from your tenant dashboard:

1. Log in to your RecruitSome account
2. Navigate to Settings → Integrations → API Keys
3. Click Create API Key
4. Give your API key a descriptive name (e.g., "Production Integration" or "Development Testing")
5. Click Generate Key
6. Important: Copy and securely store your API key immediately. For security reasons, you won't be able to see it again.

API Key Permissions

Each API key can be scoped to specific permissions, following the principle of least privilege. When creating a key, select only the permissions your integration needs:

• Career Website: vacancies, applications, locations, team, articles
• Chrome Plugin: candidates (read + write), team

If a request is made to an endpoint the API key doesn't have access to, a 403 Forbidden response with the INSUFFICIENT_SCOPE error code is returned.

2. Make Your First Request

Let's test your API key with a simple health check:

curl -X GET https://app\.recruitsome\.com/api/v1/health \
  -H "Authorization: Bearer YOUR_API_KEY"

A successful response will look like:

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

Pagination

All list endpoints return paginated results to ensure optimal performance. The API uses cursor-based pagination with the following parameters:

Pagination Response Structure

{
  "data": [...],
  "links": {
    "first": "https://app\.recruitsome\.com/api/v1/vacancies?page=1",
    "last": "https://app\.recruitsome\.com/api/v1/vacancies?page=5",
    "prev": null,
    "next": "https://app\.recruitsome\.com/api/v1/vacancies?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "path": "https://app\.recruitsome\.com/api/v1/vacancies",
    "per_page": 20,
    "to": 20,
    "total": 95
  }
}

Example: Iterating Through Pages

let page = 1;
let hasMore = true;

while (hasMore) {
  const response = await fetch(
    https://app\.recruitsome\.com/api/v1/vacancies?page=${page}&per_page=50,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );
  
  const data = await response.json();
  
  // Process the vacancies
  processVacancies(data.data);
  
  // Check if there are more pages
  hasMore = data.meta.current_page < data.meta.last_page;
  page++;
}

Rate Limiting

To ensure fair usage and maintain service quality:

• API requests are limited to 60 requests per minute
• Rate limit information is included in response headers:

- X-RateLimit-Remaining: Requests remaining in current window

- X-RateLimit-Reset: Unix timestamp when the limit resets

Response Formats

All API responses are returned in JSON format with UTF-8 encoding.

Successful Response

{
  "data": {
    // Response data
  }
}

Error Response

{
  "message": "Error description",
  "errors": {
    "field": ["Validation error message"]
  }
}

HTTP Status Codes

Next Steps

• List Published Vacancies - Learn how to retrieve and filter vacancy listings
• Get Vacancy Details - Access complete vacancy information
• API Reference - Complete API endpoint documentation