Vacatures ophalen

Haal een gepagineerde lijst op van actieve vacaturepublicaties. Dit is de feed die je carrièrewebsite gebruikt om de vacatureoverzichtspagina te tonen, met filtering, sortering en optionele facettellingen voor het bouwen van filter-UI's.

Authenticatie

Vereist een API sleutel met het vacancies:read scope (inbegrepen in de Carrièrewebsite-preset). Een sleutel zonder dit scope ontvangt een 403-respons.

Queryparameters

Parameter	Type	Standaard	Beschrijving
`page`	integer	1	Paginanummer voor paginering
`per_page`	integer	20	Items per pagina (max: 100)
`search`	string	-	Zoek in titel en samenvatting (hoofdletterongevoelig)
`language`	string	-	Filter op taalcode (exact 2 tekens, bijv. `nl`). Stelt ook de locale in voor vertaalde velden.
`location_id`	integer	-	Filter op één locatie-ID. Arraynotatie wordt hier niet geaccepteerd (geeft een `422`). Gebruik het facets-endpoint of herhaal verzoeken per locatie.
`department_id`	integer	-	Filter op één afdeling-ID. Arraynotatie wordt hier niet geaccepteerd (geeft een `422`).
`company_location_id[]`	array	-	Filter op bedrijfslocatie-ID('s) (werklocatie, voor bureautenants). Dit is het enige ID-filter op dit endpoint dat meerdere waarden accepteert: `company_location_id[]=1&company_location_id[]=2`
`experience_levels[]`	array	-	Filter op ervaringsniveau-ID's
`education_levels[]`	array	-	Filter op opleidingsniveau-ID's
`job_types[]`	array	-	Filter op dienstverband-ID's
`tags[]`	array	-	Filter op tag-ID's (hoofdtags nemen subtags automatisch mee)
`sort`	string	published_at	Sorteerveld: `published_at`, `title`, `created_at`
`sort_direction`	string	desc	Sorteerrichting: `asc` of `desc`
`include`	string	-	Aanvullende data meeladen: `facets`
`include_media`	boolean	false	`header_image` en `images` meeladen
`include_compensation`	boolean	false	Basisgegevens over salaris meeladen
`include_company_name`	boolean	false	Bedrijfsnaam opnemen in het `company_location`-object (opt-in vanwege privacy)

Responsevelden

Veld	Type	Beschrijving
`id`	integer	Uniek publicatie-ID van de vacature
`slug`	string	URL-vriendelijke identifier
`title`	string	Vacaturetitel
`summary`	string	Korte beschrijving (HTML)
`language`	string	Taalcode (ISO 639-1)
`published_at`	string	ISO 8601 publicatiedatum
`ends_at`	string\|null	ISO 8601 vervaldatum
`views_count`	integer	Aantal keer bekeken
`location`	object\|null	Locatiegegevens (kantoor-/vestigingslocatie)
`company_location`	object\|null	Bedrijfslocatiegegevens (daadwerkelijke werklocatie, voor bureauomgevingen)
`department`	object\|null	Afdelingsgegevens
`hiring_manager`	object\|null	Gegevens van de hiring manager
`education_levels`	array	Vereiste opleidingsniveaus (kan leeg zijn)
`job_types`	array	Dienstverbandtypes (kan leeg zijn)
`experience_levels`	array	Ervarings-/senioriteitsniveaus (bijv. Junior, Medior, Senior, Lead; kan leeg zijn)
`work_arrangement`	object	Werkmodel: op locatie, hybride of remote. De sleutel ontbreekt wanneer er geen werkmodel is ingesteld voor de vacature.
`tags`	array	Functiecategorietags (hoofd- en subcategorieën; kan leeg zijn)
`classification`	object\|null	Het classificatielabel van de tenant (`name`, stabiele `key`, `color`). De sleutel ontbreekt tenzij de tenant vacatureclassificatie heeft ingeschakeld. `null` wanneer het wel is ingeschakeld maar er geen label is toegewezen.
`application_url`	string	URL om te solliciteren op deze positie
`metadata`	object	Aanvullende vacaturemetadata
`header_image`	object\|null	URL's van de headerafbeelding. De sleutel ontbreekt tenzij `include_media=true`.
`images`	object	Overzicht van alle geconfigureerde afbeeldingsuitsneden. De sleutel ontbreekt tenzij `include_media=true`.
`compensation`	object\|null	Basisgegevens over beloning. De sleutel ontbreekt tenzij `include_compensation=true`.

Null vs. afwezig

De kernrelatievelden (location, company_location, department, hiring_manager) zijn altijd aanwezig in de response. Ze zijn null wanneer de vacature er geen waarde voor heeft. De optionele velden (header_image, images, compensation) en work_arrangement gedragen zich anders: wanneer niet aan de voorwaarde is voldaan, wordt de sleutel volledig weggelaten in plaats van op null gezet. Controleer of de sleutel bestaat voordat je deze uitleest.

Objectstructuren

Locatieobject

JSON

{
  "id": 3,
  "name": "Amsterdam Office",
  "city": "Amsterdam",
  "country_code": "NL",
  "country_name": "Netherlands"
}

Bedrijfslocatieobject

De werklocatie voor bureauvacatures. Geeft null terug voor niet-bureautenants of wanneer er geen bedrijfslocatie is toegewezen.

JSON

{
  "id": 17,
  "name": "Shell Pernis Refinery",
  "city": "Rotterdam",
  "country_code": "NL",
  "country_name": "Netherlands",
  "company_name": "Shell Nederland B.V."
}

De sleutel company_name is alleen aanwezig wanneer include_company_name=true wordt meegegeven. Dit is opt-in om te voorkomen dat per ongeluk zichtbaar wordt voor welk klantbedrijf een bureau werft.

Afdelingsobject

JSON

{
  "id": 5,
  "name": "Maintenance & Engineering"
}

Hiring manager-object

Het veld avatar is een enkele URL-string die verwijst naar de middelgrote avatar (256×256), of null wanneer er geen avatar is geüpload. Het is geen object met meerdere formaten.

JSON

{
  "given_name": "Sanne",
  "family_name": "de Vries",
  "full_name": "Sanne de Vries",
  "job_title": "Recruitment Manager",
  "email": "[email protected]",
  "avatar": "https://app.recruitsome.com/media/avatars/12/medium.jpg"
}

Opleidingsniveau-object

JSON

{
  "id": 1,
  "name": "Bachelor"
}

Dienstverbandtype-object

JSON

{
  "id": 1,
  "name": "Full-time"
}

Ervaringsniveau-object

JSON

{
  "id": 3,
  "name": "Senior"
}

Mogelijke waarden: Junior, Medior, Senior, Lead. Geeft een lege array terug wanneer er geen ervaringsniveau is toegewezen.

Werkmodel-object

JSON

{
  "value": "hybrid",
  "label": "Hybride"
}

Het veld value bevat de canonieke identifier: on_site, remote of hybrid. Het label is de gelokaliseerde weergavenaam (volgt de language-parameter). Let op: deze sleutel wordt volledig weggelaten wanneer er geen werkmodel is ingesteld voor de vacature.

Tag-object

JSON

{
  "id": 5,
  "name": "Software Engineer",
  "type": "sub",
  "parent_id": 1
}

Het veld type geeft aan of de tag een main-categorie of een sub-categorie is. Hoofdtags hebben parent_id: null.

Classificatieobject

JSON

{
  "name": "Priority A",
  "key": "priority_a",
  "color": "rose"
}

key is een stabiele identifier die is afgeleid van de labelnaam. Deze blijft behouden bij hernoemingen, dus gebruik key om op te matchen in plaats van name. color is een van rose, amber, emerald, sky, violet, gray of null.

Metadata-object

JSON

{
  "status": "active"
}

Beloningsobject (wanneer `include_compensation=true`)

Beknopt beloningsoverzicht voor de lijstweergave:

JSON

{
  "salary_range": {
    "min": 3500,
    "max": 5000,
    "currency": "EUR",
    "period": "monthly"
  },
  "contract_hours": 40
}

salary_range is null wanneer er geen salaris is ingesteld voor de vacature. Gebruik voor volledige beloningsgegevens (inclusief de vakantiegeldspecificatie) het detail-endpoint met include_compensation=true.

Headerafbeeldingsobject (legacy, wanneer `include_media=true`)

JSON

{
  "small": "https://app.recruitsome.com/media/vacancies/412/header-small.jpg",
  "medium": "https://app.recruitsome.com/media/vacancies/412/header-medium.jpg",
  "large": "https://app.recruitsome.com/media/vacancies/412/header-large.jpg",
  "xlarge": "https://app.recruitsome.com/media/vacancies/412/header-xlarge.jpg",
  "original": "https://app.recruitsome.com/media/vacancies/412/header.jpg"
}

Afbeeldingsobject (wanneer `include_media=true`)

Overzicht van alle geconfigureerde afbeeldingsuitsneden. De sleutel default komt overeen met de legacy header_image. Elke vermelding bevat ook interne variant_settings- en photo_library_item_id-metadata die je kunt negeren.

JSON

{
  "default": {
    "url": "https://app.recruitsome.com/media/vacancies/412/header-large.jpg",
    "width": 1200,
    "height": 675,
    "mime_type": "image/jpeg"
  },
  "narrow_casting": {
    "url": "https://app.recruitsome.com/media/vacancies/412/narrow-casting.jpg",
    "width": 1080,
    "height": 1920,
    "mime_type": "image/jpeg"
  }
}

Voorbeeld

curl -X GET "https://app.recruitsome.com/api/v1/vacancies?search=engineer&location_id=3&include_compensation=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

const params = new URLSearchParams({
  search: 'engineer',
  location_id: '3',
  include_compensation: 'true'
});

const response = await fetch(`https://app.recruitsome.com/api/v1/vacancies?${params}`, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Accept': 'application/json'
  }
});

const vacancies = await response.json();

Respons `200`

JSON

{
  "data": [
    {
      "id": 412,
      "slug": "maintenance-engineer",
      "title": "Maintenance Engineer",
      "summary": "<p>Keep our Rotterdam production lines running as part of a five-person technical service team.</p>",
      "language": "en",
      "published_at": "2026-05-12T09:00:00+00:00",
      "ends_at": "2026-07-12T23:59:59+00:00",
      "views_count": 42,
      "location": {
        "id": 3,
        "name": "Amsterdam Office",
        "city": "Amsterdam",
        "country_code": "NL",
        "country_name": "Netherlands"
      },
      "company_location": null,
      "department": {
        "id": 5,
        "name": "Maintenance & Engineering"
      },
      "hiring_manager": {
        "given_name": "Sanne",
        "family_name": "de Vries",
        "full_name": "Sanne de Vries",
        "job_title": "Recruitment Manager",
        "email": "[email protected]",
        "avatar": null
      },
      "education_levels": [
        {
          "id": 1,
          "name": "Bachelor"
        }
      ],
      "job_types": [
        {
          "id": 1,
          "name": "Full-time"
        }
      ],
      "experience_levels": [
        {
          "id": 3,
          "name": "Senior"
        }
      ],
      "work_arrangement": {
        "value": "hybrid",
        "label": "Hybrid"
      },
      "tags": [
        {
          "id": 1,
          "name": "Engineering",
          "type": "main",
          "parent_id": null
        },
        {
          "id": 5,
          "name": "Maintenance Engineer",
          "type": "sub",
          "parent_id": 1
        }
      ],
      "classification": {
        "name": "Priority A",
        "key": "priority_a",
        "color": "rose"
      },
      "compensation": {
        "salary_range": {
          "min": 3500,
          "max": 5000,
          "currency": "EUR",
          "period": "monthly"
        },
        "contract_hours": 40
      },
      "application_url": "https://www.yourcompany.com/vacatures/maintenance-engineer",
      "metadata": {
        "status": "active"
      }
    }
  ],
  "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": 94
  }
}

Wanneer include=facets is opgegeven, wordt een facets-object toegevoegd aan meta (de sleutel is anders afwezig) met geaggregeerde tellingen per filteroptie. De structuur is identiek aan het antwoord van het zelfstandige facets-endpoint:

JSON

{
  "meta": {
    "facets": {
      "locations": [
        {
          "id": 3,
          "name": "Amsterdam Office",
          "city": "Amsterdam",
          "country_code": "NL",
          "country_name": "Netherlands",
          "count": 15,
          "selected": false
        }
      ],
      "company_locations": [
        {
          "id": 17,
          "name": "Shell Pernis Refinery",
          "city": "Rotterdam",
          "country_code": "NL",
          "country_name": "Netherlands",
          "count": 5,
          "selected": false
        }
      ],
      "departments": [
        {
          "id": 5,
          "name": "Maintenance & Engineering",
          "count": 23,
          "selected": false
        }
      ],
      "experience_levels": [
        {
          "id": 3,
          "name": "Senior",
          "count": 12,
          "selected": false
        }
      ],
      "education_levels": [
        {
          "id": 8,
          "name": "Bachelor",
          "count": 28,
          "selected": false
        }
      ],
      "job_types": [
        {
          "id": 1,
          "name": "Full-time",
          "count": 45,
          "selected": false
        }
      ],
      "tags": [
        {
          "id": 1,
          "name": "Engineering",
          "count": 32,
          "selected": false,
          "sub_tags": [
            {
              "id": 5,
              "name": "Maintenance Engineer",
              "count": 18,
              "selected": false
            },
            {
              "id": 6,
              "name": "Service Technician",
              "count": 8,
              "selected": false
            }
          ]
        }
      ],
      "languages": [
        {
          "code": "en",
          "name": "English",
          "count": 38,
          "selected": false
        }
      ]
    }
  }
}

De tags-facet gebruikt een hiërarchische structuur waarbij hoofdcategorieën geneste sub_tags bevatten. Wanneer je filtert op een hoofdtag, worden alle bijbehorende subtags automatisch meegenomen.

Opmerkingen

Alleen actieve publicaties van het websitekanaal worden geretourneerd
Resultaten worden standaard gesorteerd op published_at (aflopend)
De lijstweergave bevat geen volledige functieomschrijvingen, eisen of aanbiedingen. Gebruik het detail-endpoint voor volledige vacature-informatie.
Bij het filteren op een hoofdtag worden alle bijbehorende subtags automatisch meegenomen (cascade-filtering)
Salarisbedragen zijn in de basisvaluta-eenheid (bijv. 3500 = €3.500)
Het compensatiesalaris komt uit de eigen velden van de vacature. Voor uren wordt teruggevallen op de gekoppelde arbeidsvoorwaarden (CompanyRemuneration) als de vacature geen uren heeft ingesteld.
classification is alleen aanwezig voor tenants die vacatureclassificatie hebben ingeschakeld (Instellingen → Vacatures). De waarde is null wanneer de functie is ingeschakeld maar de vacature geen label heeft. Het is geen filterbaar queryparameter op dit endpoint.

Authenticatie

Queryparameters

Responsevelden

Objectstructuren

Locatieobject

Bedrijfslocatieobject

Afdelingsobject

Hiring manager-object

Opleidingsniveau-object

Dienstverbandtype-object

Ervaringsniveau-object

Werkmodel-object

Tag-object

Classificatieobject

Metadata-object

Beloningsobject (wanneer `include_compensation=true`)

Headerafbeeldingsobject (legacy, wanneer `include_media=true`)

Afbeeldingsobject (wanneer `include_media=true`)

Voorbeeld

Respons `200`

Facets

Opmerkingen

Lees ook

Vacatures ophalen

Authenticatie

Queryparameters

Responsevelden

Objectstructuren

Locatieobject

Bedrijfslocatieobject

Afdelingsobject

Hiring manager-object

Opleidingsniveau-object

Dienstverbandtype-object

Ervaringsniveau-object

Werkmodel-object

Tag-object

Classificatieobject

Metadata-object

Beloningsobject (wanneer include_compensation=true)

Headerafbeeldingsobject (legacy, wanneer include_media=true)

Afbeeldingsobject (wanneer include_media=true)

Voorbeeld

Respons 200

Facets

Opmerkingen

Lees ook

Beloningsobject (wanneer `include_compensation=true`)

Headerafbeeldingsobject (legacy, wanneer `include_media=true`)

Afbeeldingsobject (wanneer `include_media=true`)

Respons `200`