List Vacancies

Retrieve a paginated list of active vacancy publications with filtering and sorting options.

Endpoint

GET /api/v1/vacancies

Query Parameters

Response Fields

Object Structures

Location Object

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

Company Location Object

The work site location for agency vacancies. Returns null for non-agency tenants or when no company location is assigned.

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

Department Object

{
  "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://..."
  }
}

Education Level Object

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

Job Type Object

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

Experience Level Object

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

Possible values: Junior, Medior, Senior, Lead. Returns an empty array when no experience level is assigned.

Work Arrangement Object

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

The value field contains the canonical identifier (on-site, Fully remote, Hybrid remote). The label is the localized display name.

Tag Object

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

The type field indicates whether the tag is a main category or a sub category. Main tags have parent_id: null.

Metadata Object

{
  "status": "active"
}

Compensation Object (when include_compensation=true)

Basic compensation summary for list view:

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

Note: For full compensation details (including holidays breakdown), use the detail endpoint with include_compensation=true.

Header Image Object (Legacy, when include_media=true)

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

Images Object (when include_media=true)

Map of all configured image crops. The 'default' key corresponds to the 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

The response includes pagination metadata:

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

When include=facets is specified, the response includes aggregated counts for 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
        }
      ]
    }
  }
}

Note: The tags facet uses a hierarchical structure where main categories contain nested sub_tags. When filtering by a main tag, all its sub-tags are automatically included.

Example Request

Basic Request

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

With Filters and Options

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"

Example Response

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

Notes

• Only active publications from the internal channel are returned
• Results are sorted by published_at descending by default
• The list view does not include full job descriptions, requirements, or offers
• Use the detail endpoint to get complete vacancy information
• Education levels, job types, and tags arrays may be empty if none are specified
• When filtering by a main tag, all its sub-tags are automatically included (cascade filtering)
• Salary amounts are in the base currency unit (e.g., 3500 = €3,500)
• Compensation salary uses the vacancy's own fields as primary source; hours fall back to employment conditions (CompanyRemuneration) if the vacancy has no hours set