Updated June 15, 2026
GET
/api/v1/articles
curl -X GET \
"https://app.recruitsome.com/api/v1/articles" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"const response = await fetch('https://app.recruitsome.com/api/v1/articles', {
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/articles');
$data = $response->json();Retrieve a paginated list of published articles available on the website channel.
Authentication
Requires an API key with the articles:read scope (included in the Career Website preset). Calls with a key that lacks the scope return a 403 with error code INSUFFICIENT_SCOPE.
Endpoint
GET /api/v1/articlesQuery Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer | 1 | Page number for pagination |
per_page | integer | 20 | Items per page (max: 100) |
language | string | - | ISO 639-1 language code (e.g., nl, en). Filters articles that have content in this language and sets the response locale. |
type | string | - | Filter by article type (max 30 chars). Known values: news, company_update, event, blog_post |
search | string | - | Search in title and excerpt (case-insensitive) |
tags[] | array | - | Filter by tag IDs (main tags cascade to include sub-tags) |
is_featured | boolean | - | Pass a truthy value (1, true, yes, on) to return 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 Fields
| Field | Type | Description |
|---|---|---|
id | integer | Unique article ID |
slug | string | URL-friendly identifier |
type | string | Article type: news, company_update, event, blog_post |
title | string | Article title |
excerpt | string|null | Brief summary/teaser text |
language | string | Language code of the returned content |
published_at | string | ISO 8601 publication date |
expires_at | string|null | ISO 8601 expiration date |
views_count | integer | Number of times viewed |
is_featured | boolean | Whether the article is featured |
estimated_reading_time | integer | Estimated reading time in minutes |
featured_image | object|null | Featured image URLs (only when include_media=true) |
tags | array | Article tags |
author | object|null | Article author information |
available_languages | array | List of available language codes |
metadata | object | Additional article metadata |
Featured Image Object
{
"original": "https://cdn.example.com/images/article-original.jpg",
"thumb": "https://cdn.example.com/images/article-thumb.jpg",
"medium": "https://cdn.example.com/images/article-medium.jpg"
}Tag Object
{
"id": 5,
"name": "Company Culture",
"type": "sub",
"parent_id": 1
}Author Object
{
"given_name": "Jane",
"family_name": "Smith",
"full_name": "Jane Smith",
"avatar": null
}Metadata Object
{
"type_label": "News",
"channels": ["website", "employee_self_service"]
}Possible channel values: website, employee_self_service, approver_self_service.
Example Request
curl -X GET "https://app.recruitsome.com/api/v1/articles?language=nl&type=news&include_media=true" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Accept: application/json"Example Response
{
"data": [
{
"id": 1,
"slug": "welkom-bij-ons-team-nl",
"type": "news",
"title": "Welkom bij ons team",
"excerpt": "Een warm welkom aan onze nieuwe collega's die deze maand zijn gestart.",
"language": "nl",
"published_at": "2026-02-01T09:00:00+00:00",
"expires_at": null,
"views_count": 150,
"is_featured": true,
"estimated_reading_time": 3,
"featured_image": {
"original": "https://cdn.example.com/images/welcome.jpg",
"thumb": "https://cdn.example.com/images/welcome-thumb.jpg",
"medium": "https://cdn.example.com/images/welcome-medium.jpg"
},
"tags": [
{
"id": 1,
"name": "Bedrijfsnieuws",
"type": "main",
"parent_id": null
}
],
"author": {
"given_name": "Jane",
"family_name": "Smith",
"full_name": "Jane Smith",
"avatar": null
},
"available_languages": ["nl", "en"],
"metadata": {
"type_label": "Nieuws",
"channels": ["website", "employee_self_service"]
}
}
],
"links": {
"first": "...?page=1",
"last": "...?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"per_page": 20,
"to": 1,
"total": 1
}
}Errors
| Status | When | Body |
|---|---|---|
422 | A tags[] entry isn't an integer or doesn't reference an existing tag | {"message": "The given data was invalid.", "errors": {"tags.0": ["The selected tags.0 is invalid."]}} |
422 | language isn't exactly 2 characters, or type exceeds 30 characters | Same shape, with the offending field in errors |
401 | Missing or invalid API key | {"message": "Unauthenticated."} |
403 | API key lacks the articles:read scope | {"message": "This API key does not have the required permission: articles:read", "error": "INSUFFICIENT_SCOPE", "required_scope": "articles:read"} |
Notes
- Only articles with status
published, channelwebsite, and valid date range are returned - Scheduled articles (with
publish_atin the future) are excluded - Expired articles (with
expires_atin the past) are excluded - Soft-deleted articles are automatically excluded
- The
searchparameter performs case-insensitive matching across title and excerpt - Main tags in the
tags[]filter automatically include their sub-tags is_featuredonly filters when truthy — passingis_featured=false(or0) is a no-op and returns the full list, not "non-featured articles only"typeis not validated against a fixed list: an unknown value (up to 30 chars) returns an empty list rather than a422