Updated June 15, 2026
GET
/api/v1/locations
curl -X GET \
"https://app.recruitsome.com/api/v1/locations" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"const response = await fetch('https://app.recruitsome.com/api/v1/locations', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Accept': 'application/json',
},
});
const data = await response.json();
console.log(data);use Illuminate\Support\Facades\Http;
$response = Http::withToken('YOUR_API_KEY')
->acceptJson()
->get('https://app.recruitsome.com/api/v1/locations');
$data = $response->json();Retrieve a paginated list of your office locations — for example to show your offices on your careers site, complete with addresses and optional map coordinates.
Authentication
Requires an API key with the locations:read scope (included in the Career website preset). A key without this scope receives a 403 response.
Query parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer | 1 | Page number for pagination |
per_page | integer | 20 | Items per page (max: 100) |
language | string | - | Set response locale for country names (exactly 2 characters) |
country_code | string | - | Filter by country code (2 characters, e.g. NL) |
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 number of vacancies at each location |
Response fields
| Field | Type | Description |
|---|---|---|
id | integer | Unique location ID |
slug | string | URL-friendly identifier |
name | string | Location name |
address | object | Full address details |
coordinates | object | Latitude/longitude. Key is absent unless include_coordinates=true — it is not included as null. |
vacancy_count | integer | Number of vacancies linked to this location. Key is absent unless include_vacancy_count=true. |
vacancy_count counts all vacancies linked to the location — including drafts, closed, and unpublished ones — not just the vacancies currently visible on GET /vacancies. Don't use it as a "open positions here" badge without checking against the vacancy list.
Address object
{
"address_line_1": "Keizersgracht 100",
"address_line_2": null,
"address_line_3": null,
"locality": "Amsterdam",
"administrative_area": "North Holland",
"postal_code": "1015 AA",
"country_code": "NL",
"country_name": "Netherlands"
}Coordinates object
{
"latitude": 52.3676,
"longitude": 4.9041
}Example
curl -X GET "https://app.recruitsome.com/api/v1/locations?country_code=NL&include_coordinates=true" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"Response 200
{
"data": [
{
"id": 1,
"slug": "amsterdam-office-amsterdam-nl",
"name": "Amsterdam Office",
"address": {
"address_line_1": "Keizersgracht 100",
"address_line_2": null,
"address_line_3": null,
"locality": "Amsterdam",
"administrative_area": "North Holland",
"postal_code": "1015 AA",
"country_code": "NL",
"country_name": "Netherlands"
},
"coordinates": {
"latitude": 52.3676,
"longitude": 4.9041
}
}
],
"links": {
"first": "https://app.recruitsome.com/api/v1/locations?page=1",
"last": "https://app.recruitsome.com/api/v1/locations?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"per_page": 20,
"to": 1,
"total": 1
}
}Error responses
| Status | When | Fix |
|---|---|---|
401 | Missing or invalid API key | Send a valid key as Authorization: Bearer YOUR_API_KEY |
403 | API key lacks the locations:read scope | Add the scope to your key or regenerate it with the Career website preset |
422 | Invalid query parameter (e.g. language or country_code not exactly 2 characters) | Correct the parameter per the table above |
Notes
- Deleted locations are automatically excluded
- Country names are localized based on the
languageparameter - The
searchparameter performs case-insensitive matching across name, city, and street address