Introduction

The Recruitsome API gives you programmatic access to your published vacancy data, so you can power your career website, job boards, and HR integrations directly from Recruitsome.

Base URL

All API requests go to:

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

Authentication

The Recruitsome API uses Bearer token authentication. Include your API key in the Authorization header of every request:

Authorization: Bearer YOUR_API_KEY

Getting started

1. Create an API key

1. Log in to your Recruitsome account
2. Go to Settings → API Keys
3. Click Create API Key (or Create Your First API Key if you don't have any keys yet)
4. Pick a preset under Quick Setup, or select individual Permissions
5. Give your key a descriptive Key Name (e.g., "Career Website" or "Indeed Plugin")
6. Click Create API Key

Your new key appears once in the New API Key Generated modal — copy it right away. For security reasons, it won't be shown again.

API key permissions

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

Presets are available for common use cases:

• Career Website: vacancies (read + write), applications, locations, team, articles
• Chrome Plugin: candidates (read + write), team
• Full Access: all available permissions

If you call an endpoint your API key doesn't have access to, you get a 403 Forbidden response with the INSUFFICIENT_SCOPE error code.

2. Make your first request

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 looks like:

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

Pagination

All list endpoints return paginated results. The API uses page-based pagination — request a specific page with the page parameter and read your position from the meta object:

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

Three write endpoints are rate limited because they trigger heavier processing:

The read endpoints have no fixed per-key limit today — still, keep your request rate modest and cache responses where you can; limits may be introduced later.

Rate-limited endpoints include these headers in their responses:

• X-RateLimit-Limit: maximum requests per minute
• X-RateLimit-Remaining: requests remaining in the current window

When you exceed the limit, the 429 response also includes:

• Retry-After: seconds to wait before retrying
• 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