Vacaturedetails

Haal alle details op van een specifieke vacaturepublicatie. Alles wat je carrièrewebsite nodig heeft om een volledige vacaturepagina te tonen: volledige vacatureteksten, media, hiring manager en (optioneel) compensatie.

Authenticatie

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

Padparameters

Parameter	Type	Beschrijving
`slug`	string	De publicatie-slug (URL-vriendelijke identifier), exact zoals geretourneerd door het list-endpoint

Queryparameters

Parameter	Type	Standaard	Beschrijving
`language`	string	-	ISO 639-1 taalcode (bijv. `nl`, `en`). Bepaalt de taal voor vertaalde velden zoals opleidingsniveaus, dienstverbandtypes en het label voor de werklocatievorm.
`include_compensation`	boolean	false	Compensatiegegevens meenemen
`include_media`	boolean	-	Wordt geaccepteerd, maar heeft geen effect op dit endpoint: `header_image` en `images` worden altijd meegeleverd in de detailrespons. (Deze vlag is alleen relevant voor het list-endpoint.)
`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 (wordt bij elk verzoek opgehoogd)
`header_image`	object\|null	Header-afbeelding-URL's in meerdere formaten (legacy, gekoppeld aan de `default`-crop). Altijd aanwezig op dit endpoint.
`images`	object	Map van alle geconfigureerde afbeeldingscrops. Altijd aanwezig op dit endpoint.
`job_description`	string	Volledige functiebeschrijving (HTML)
`job_requirements`	string	Functie-eisen (HTML)
`job_offer`	string	Wat het bedrijf biedt (HTML)
`company_description`	string\|null	Bedrijfsbeschrijving in de taal van de vacature (valt terug op de bronbeschrijving)
`location`	object\|null	Locatiegegevens (kantoor-/vestigingslocatie)
`company_location`	object\|null	Bedrijfslocatiegegevens (daadwerkelijke werkplek, voor bureauomgevingen)
`department`	object\|null	Afdelingsgegevens
`hiring_manager`	object\|null	Informatie over de hiring manager
`education_levels`	array	Vereiste opleidingsniveaus (kan leeg zijn)
`job_types`	array	Dienstverbandtypen (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 voor deze vacature. De sleutel ontbreekt tenzij de tenant vacatureclassificatie heeft ingeschakeld. `null` wanneer classificatie is ingeschakeld maar er geen label is toegewezen.
`language_proficiencies`	array\|null	Vereiste taalvaardigheden. `null` wanneer er geen taaleisen zijn ingesteld (geen lege array).
`application_url`	string	URL om te solliciteren op deze functie
`metadata`	object	Aanvullende metadata van de vacature
`compensation`	object	Beloningsgegevens. De sleutel ontbreekt tenzij `include_compensation=true` is meegegeven.

Objectstructuren

Images-object

Geeft een map terug van alle geconfigureerde afbeeldingscrops. De default-sleutel komt overeen met de legacy header_image-URL. Elke entry 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"
  }
}

Header image-object (legacy)

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"
}

Location-object

JSON

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

Company location-object

De werkpleklocatie 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.

Department-object

JSON

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

Hiring manager-object

Het veld avatar is een enkele URL-string die verwijst naar de medium-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"
}

Education level-object

JSON

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

Job type-object

JSON

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

Experience level-object

JSON

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

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

Work arrangement-object

JSON

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

Het veld value bevat de canonieke identifier: on_site, remote of hybrid. Het veld label is de gelokaliseerde weergavenaam (volgt de language-queryparameter). Deze sleutel wordt volledig weggelaten wanneer de vacature geen werkmodel heeft ingesteld.

Tag-object

JSON

{
  "id": 5,
  "name": "Maintenance 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.

Classification-object

JSON

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

key is een stabiele identifier die is afgeleid van de labelnaam bij aanmaak. Deze verandert nooit wanneer het label wordt hernoemd. Gebruik daarom key (en niet name) wanneer je logica bouwt rondom een classificatie. color is een van een vast kleurenpalet (rose, amber, emerald, sky, violet, gray) of null.

Language proficiency-object

JSON

{
  "language_code": "en",
  "speaking_level": "Professional",
  "reading_level": "Professional",
  "writing_level": "Professional"
}

Metadata-object

JSON

{
  "status": "active"
}

Compensation-object (wanneer `include_compensation=true`)

Het compensation-object kan salaris, uren, vakantiedagen en aanvullende informatie bevatten:

salary: uit de eigen velden van de vacature (min/max in de basisvaluta-eenheid, valuta, periode)
hours: uit de eigen velden van de vacature, met terugval op de gekoppelde arbeidsvoorwaarden (CompanyRemuneration)
holidays: uit de gekoppelde arbeidsvoorwaarden (CompanyRemuneration). Alle dagwaarden zijn floats, gedeeltelijke dagen zoals 12.5 komen voor.
additional_info: vrije-tekstvelden vastgelegd op de vacature, met optionele sleutels specialty_benefits en compensation_notes

JSON

{
  "salary": {
    "min": 3500,
    "max": 5000,
    "currency": "EUR",
    "period": "monthly"
  },
  "hours": {
    "min_per_week": 32,
    "max_per_week": 40
  },
  "holidays": {
    "total_days": 38.5,
    "breakdown": {
      "statutory": 20,
      "non_statutory": 5.5,
      "adv": 13
    }
  },
  "additional_info": {
    "specialty_benefits": "Company van and toolkit provided for on-call shifts.",
    "compensation_notes": "Salary depends on relevant certifications (VCA, NEN 3140)."
  }
}

Elke sectie wordt weggelaten wanneer er geen gegevens beschikbaar zijn: een vacature zonder ingesteld salaris heeft geen salary-sleutel, en nulwaarden worden verwijderd uit de holidays.breakdown.

Gestructureerde arbeidsvoorwaarden zoals pensioen, vakantiegeld, dertiende maand, reiskostenvergoeding en thuiswerkvergoeding worden niet via de API ontsloten. Alles buiten salaris, uren en vakantiedagen verschijnt alleen als vrije tekst in additional_info, mits het op de vacature is vastgelegd.

Voorbeeld

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

const response = await fetch(
  'https://app.recruitsome.com/api/v1/vacancies/maintenance-engineer?include_compensation=true&language=nl',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Accept': 'application/json'
    }
  }
);

const vacancy = await response.json();

Response `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,
    "header_image": {
      "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"
    },
    "images": {
      "default": {
        "url": "https://app.recruitsome.com/media/vacancies/412/header-large.jpg",
        "width": 1200,
        "height": 675,
        "mime_type": "image/jpeg"
      }
    },
    "job_description": "<h2>About the role</h2><p>As Maintenance Engineer you keep three production lines running...</p>",
    "job_requirements": "<h2>Requirements</h2><ul><li>Completed MBO 4 in mechatronics</li><li>VCA certificate</li></ul>",
    "job_offer": "<h2>What we offer</h2><ul><li>Salary between €3,500 and €5,000</li><li>38.5 vacation days</li></ul>",
    "company_description": "<p>We are a Rotterdam-based production company with 240 employees...</p>",
    "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": "Hybride"
    },
    "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"
    },
    "language_proficiencies": [
      {
        "language_code": "en",
        "speaking_level": "Professional",
        "reading_level": "Professional",
        "writing_level": "Professional"
      }
    ],
    "compensation": {
      "salary": {
        "min": 3500,
        "max": 5000,
        "currency": "EUR",
        "period": "monthly"
      },
      "hours": {
        "min_per_week": 32,
        "max_per_week": 40
      },
      "holidays": {
        "total_days": 38.5,
        "breakdown": {
          "statutory": 20,
          "non_statutory": 5.5,
          "adv": 13
        }
      }
    },
    "application_url": "https://www.yourcompany.com/vacatures/maintenance-engineer",
    "metadata": {
      "status": "active"
    }
  }
}

Foutresponses

Status	Wanneer	Oplossing
`401`	Ontbrekende of ongeldige API sleutel	Stuur een geldige sleutel mee als `Authorization: Bearer YOUR_API_KEY`
`403`	De API sleutel mist het `vacancies:read` scope	Voeg het scope toe aan je sleutel of genereer een nieuwe met de Carrièrewebsite-preset
`404`	Er bestaat geen actieve websitepublicatie voor deze slug	Controleer de `slug` via het list-endpoint. Verlopen of niet-gepubliceerde vacatures geven ook een `404` terug
`422`	Ongeldige queryparameter (bijv. `language` is niet exact 2 tekens)	Corrigeer de parameter volgens de bovenstaande tabel

Opmerkingen

De views_count wordt bij elk verzoek aan dit endpoint opgehoogd
header_image en images worden op dit endpoint altijd meegeleverd. include_media heeft hier geen effect
Kernrelatievelden (location, company_location, department, hiring_manager) zijn altijd aanwezig, ook wanneer ze null zijn. De sleutels work_arrangement en compensation worden weggelaten wanneer ze niet van toepassing zijn
classification is alleen aanwezig voor tenants die vacatureclassificatie hebben ingeschakeld (Instellingen → Vacatures). De waarde is null wanneer de functie is ingeschakeld maar er geen label aan de vacature is toegewezen. Koppel integraties op de stabiele key, die behouden blijft bij het hernoemen van labels
Salarisbedragen zijn in de basiseenheid van de valuta (bijv. 3500 = € 3.500)

Lokalisatie

Wanneer de language-parameter wordt meegegeven, worden de volgende velden in de opgegeven taal teruggegeven:

education_levels[].name — vertaalde namen van opleidingsniveaus (bijv. "Middelbaar onderwijs" voor Nederlands)
job_types[].name — vertaalde namen van dienstverbandtypen (bijv. "Voltijd" voor Nederlands)
work_arrangement.label — vertaald werkmodellabel (bijv. "Hybride" voor Nederlands)

Als er geen language-parameter wordt meegegeven, retourneert de API waarden in de standaardtaal van de applicatie.

Authenticatie

Padparameters

Queryparameters

Responsevelden

Objectstructuren

Images-object

Header image-object (legacy)

Location-object

Company location-object

Department-object

Hiring manager-object

Education level-object

Job type-object

Experience level-object

Work arrangement-object

Tag-object

Classification-object

Language proficiency-object

Metadata-object

Compensation-object (wanneer include_compensation=true)

Voorbeeld

Response 200

Foutresponses

Opmerkingen

Lokalisatie

Lees ook

Compensation-object (wanneer `include_compensation=true`)

Response `200`