Vacatures ophalen

Haal een gepagineerde lijst op van actieve vacaturepublicaties met filter- en sorteeropties.

Endpoint

GET /api/v1/vacancies

Query Parameters

Responsevelden

Objectstructuren

Locatieobject

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

Bedrijfslocatieobject

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

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

Afdelingsobject

{
  "id": 456,
  "name": "Engineering Department"
}

Hiring Manager-object

{
  "given_name": "John",
  "family_name": "Doe",
  "full_name": "John Doe",
  "job_title": "Engineering Manager",
  "email": "[email protected]",
  "avatar": {
    "small": "https://...",
    "medium": "https://...",
    "large": "https://...",
    "xlarge": "https://...",
    "original": "https://..."
  }
}

Opleidingsniveau-object

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

Dienstverbandtype-object

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

Ervaringsniveau-object

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

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

Werkmodel-object

{
  "value": "Hybrid remote",
  "label": "Hybride"
}

Het veld value bevat de canonieke identifier (on-site, Fully remote, Hybrid remote). Het label is de gelokaliseerde weergavenaam.

Tag-object

{
  "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.

Metadata-object

{
  "status": "active"
}

Compensatie-object (wanneer include_compensation=true)

Basisoverzicht van de compensatie voor de lijstweergave:

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

Let op: voor volledige compensatiedetails (inclusief vakantiedagenspecificatie) gebruik je het detail-endpoint met include_compensation=true.

Headerafbeelding-object (Legacy, wanneer include_media=true)

{
  "small": "https://...",
  "medium": "https://...",
  "large": "https://...",
  "xlarge": "https://...",
  "original": "https://..."
}

Afbeeldingen-object (wanneer include_media=true)

Overzicht van alle geconfigureerde afbeeldingsuitsneden. De sleutel 'default' komt overeen met de legacy header_image.

{
  "default": {
    "url": "https://...",
    "width": 1200,
    "height": 675,
    "mime_type": "image/jpeg"
  },
  "narrow_casting": {
    "url": "https://...",
    "width": 1080,
    "height": 1920,
    "mime_type": "image/jpeg"
  }
}

Pagination

Het antwoord bevat metadata voor pagination:

{
  "data": [...],
  "links": {
    "first": "https://api.example.com/api/v1/vacancies?page=1",
    "last": "https://api.example.com/api/v1/vacancies?page=5",
    "prev": null,
    "next": "https://api.example.com/api/v1/vacancies?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "links": [...],
    "path": "https://api.example.com/api/v1/vacancies",
    "per_page": 20,
    "to": 20,
    "total": 94,
    "facets": {...} // Only when include=facets
  }
}

Facets

Wanneer include=facets wordt meegegeven, bevat de response geaggregeerde aantallen voor filtering:

{
  "meta": {
    "facets": {
      "locations": [
        {
          "id": 1,
          "name": "Amsterdam",
          "count": 15,
          "selected": false
        }
      ],
      "company_locations": [
        {
          "id": 10,
          "name": "Shell Pernis",
          "city": "Rotterdam",
          "country_code": "NL",
          "country_name": "Netherlands",
          "count": 5,
          "selected": false
        }
      ],
      "departments": [
        {
          "id": 5,
          "name": "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": "Software Engineer",
              "count": 18,
              "selected": false
            },
            {
              "id": 6,
              "name": "DevOps Engineer",
              "count": 8,
              "selected": false
            }
          ]
        }
      ],
      "languages": [
        {
          "code": "en",
          "name": "English",
          "count": 38,
          "selected": false
        }
      ]
    }
  }
}

Let op: de tags-facet maakt gebruik van een hiërarchische structuur waarbij hoofdcategorieën geneste sub_tags bevatten. Bij het filteren op een hoofdtag worden alle bijbehorende sub-tags automatisch meegenomen.

Voorbeeldverzoek

Basisverzoek

curl -X GET https://api.example.com/api/v1/vacancies \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Met filters en opties

curl -X GET "https://api.example.com/api/v1/vacancies?search=developer&location_id=1&include_compensation=true&include=facets" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Voorbeeldrespons

{
  "data": [
    {
      "id": 123,
      "slug": "senior-developer-position",
      "title": "Senior Software Developer",
      "summary": "Join our team to build innovative solutions...",
      "language": "en",
      "published_at": "2024-01-15T09:00:00+00:00",
      "ends_at": "2024-02-15T23:59:59+00:00",
      "views_count": 42,
      "location": {
        "id": 1,
        "name": "Amsterdam Office",
        "city": "Amsterdam",
        "country_code": "NL",
        "country_name": "Netherlands"
      },
      "company_location": null,
      "department": {
        "id": 5,
        "name": "Engineering"
      },
      "hiring_manager": {
        "given_name": "John",
        "family_name": "Doe",
        "full_name": "John Doe",
        "job_title": "Engineering Manager",
        "email": "[email protected]",
        "avatar": null
      },
      "education_levels": [
        {
          "id": 1,
          "name": "Bachelor"
        }
      ],
      "job_types": [
        {
          "id": 1,
          "name": "Full-time"
        }
      ],
      "tags": [
        {
          "id": 1,
          "name": "Engineering",
          "type": "main",
          "parent_id": null
        },
        {
          "id": 5,
          "name": "Software Engineer",
          "type": "sub",
          "parent_id": 1
        }
      ],
      "application_url": "https://careers.example.com/senior-developer-position",
      "metadata": {
        "status": "active"
      }
    }
  ],
  "links": {
    "first": "https://api.example.com/api/v1/vacancies?page=1",
    "last": "https://api.example.com/api/v1/vacancies?page=5",
    "prev": null,
    "next": "https://api.example.com/api/v1/vacancies?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "path": "https://api.example.com/api/v1/vacancies",
    "per_page": 20,
    "to": 20,
    "total": 94
  }
}

Opmerkingen

• Alleen actieve publicaties van het interne kanaal worden geretourneerd
• Resultaten worden standaard gesorteerd op published_at in aflopende volgorde
• De lijstweergave bevat geen volledige functiebeschrijvingen, vereisten of aanbiedingen
• Gebruik het detail-endpoint om volledige vacature-informatie op te halen
• Arrays voor opleidingsniveaus, functietypes en tags kunnen leeg zijn als er geen zijn opgegeven
• Bij het filteren op een hoofdtag worden automatisch alle bijbehorende subtags meegenomen (cascade filtering)
• Salarisbedragen zijn in de basisvaluta-eenheid (bijv. 3500 = € 3.500)
• Het compensatiesalaris gebruikt de eigen velden van de vacature als primaire bron; uren vallen terug op de arbeidsvoorwaarden (CompanyRemuneration) als er geen uren op de vacature zijn ingesteld