Benefits

Overview

Benefits endpoints provide read access to benefits and benefit packages.

Endpoint Summary

Method	Route	Purpose
GET	/v1/benefits	List benefits
GET	/v1/benefits/{benefitId}	Get benefit by ID
GET	/v1/benefits-packages	List benefit packages
GET	/v1/benefits-packages/{packageId}	Get benefit package by ID

GET /v1/benefits

Return paginated benefits.

Headers

Header	Required	Value
Authorization	Yes	Bearer {{ACCESS_TOKEN}}
Accept	Yes	application/json

Query Parameters

Parameter	Type	Required	Description
page	number	No	Page number.
per_page	number	No	Items per page.
search_text	string	No	Search value.
name	string	No	Filter by name.
status	string	No	Filter by status.
beneficiary_type	string	No	Filter by beneficiary type.
frequency	string	No	Filter by frequency.
applies	string	No	Filter by application case.
amount_type	string	No	Filter by amount type.
order	string	No	Sort field.
order_direction	string	No	asc or desc.

Example Request

curl -X GET "{{BASE_URL}}/v1/benefits?page=1&per_page=20" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}" \
  -H "Accept: application/json"

Success Response (200)

{
  "benefits": {
    "currentPage": 1,
    "perPage": 20,
    "lastPage": 1,
    "total": 1,
    "items": [
      {
        "id": 63,
        "benefit_id": "3fddf23f-0e3d-4d6a-bc2c-c4f79fe7025c",
        "type": "benefit",
        "name": "Housing Allowance",
        "status": "active",
        "amount": "1500.00",
        "amount_percentage": null,
        "is_amount_percentage": false,
        "amount_type": "fixed",
        "currency": "EUR",
        "frequency": "monthly",
        "frequency_label": "Monthly",
        "age_min": null,
        "age_max": null,
        "beneficiary_type": "expat",
        "applies": "assignment",
        "applies_text": "Assignment",
        "payment_method": "payroll",
        "tax_free": false,
        "tax_regime": null,
        "is_visible_to_expat": true,
        "archived_at": null,
        "restricted_countries": [],
        "first_year_total": "18000.00",
        "rate_source": null,
        "client_currency_rate_id": null,
        "rate_valid_from": null,
        "rate_valid_to": null
      }
    ],
    "filters": []
  }
}

GET /v1/benefits/{benefitId}

Return one benefit by ID.

Headers

Header	Required	Value
Authorization	Yes	Bearer {{ACCESS_TOKEN}}
Accept	Yes	application/json

Path Parameters

Parameter	Type	Required	Description
benefitId	number	Yes	Benefit identifier.

Example Request

curl -X GET "{{BASE_URL}}/v1/benefits/{{BENEFIT_ID}}" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}" \
  -H "Accept: application/json"

Success Response (200)

{
  "benefit": {
    "id": 63,
    "benefit_id": "3fddf23f-0e3d-4d6a-bc2c-c4f79fe7025c",
    "type": "benefit",
    "name": "Housing Allowance",
    "status": "active",
    "amount": "1500.00",
    "amount_percentage": null,
    "is_amount_percentage": false,
    "amount_type": "fixed",
    "currency": "EUR",
    "frequency": "monthly",
    "frequency_label": "Monthly",
    "beneficiary_type": "expat",
    "applies": "assignment",
    "applies_text": "Assignment",
    "payment_method": "payroll",
    "tax_free": false,
    "is_visible_to_expat": true,
    "restricted_countries": [],
    "first_year_total": "18000.00"
  }
}

GET /v1/benefits-packages

Return paginated benefit packages.

Headers

Header	Required	Value
Authorization	Yes	Bearer {{ACCESS_TOKEN}}
Accept	Yes	application/json

Query Parameters

Parameter	Type	Required	Description
page	number	No	Page number.
per_page	number	No	Items per page.
search_text	string	No	Search value.
name	string	No	Filter by package name.
status	array<string>	No	Filter by package statuses.
assignment_id	number	No	Filter by assignment.
order	string	No	Sort field.
order_direction	string	No	asc or desc.

Example Request

curl -X GET "{{BASE_URL}}/v1/benefits-packages?page=1&per_page=20" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}" \
  -H "Accept: application/json"

Success Response (200)

{
  "packages": {
    "currentPage": 1,
    "perPage": 20,
    "lastPage": 1,
    "total": 1,
    "items": [
      {
        "id": 49,
        "name": "Relocation Core Package",
        "assignment_id": 378,
        "status": "approved",
        "currency": "EUR",
        "local_currency": "EUR",
        "is_visible_to_expat": true,
        "planned_start_date": "2026-05-01",
        "planned_end_date": "2026-09-01",
        "actual_end_date": null,
        "archived_at": null,
        "benefits": [
          {
            "id": 63,
            "benefit_id": "3fddf23f-0e3d-4d6a-bc2c-c4f79fe7025c",
            "type": "benefit",
            "name": "Housing Allowance",
            "status": "active",
            "amount": "1500.00",
            "amount_type": "fixed",
            "currency": "EUR",
            "frequency": "monthly",
            "frequency_label": "Monthly",
            "beneficiary_type": "expat",
            "applies": "assignment",
            "payment_method": "payroll",
            "tax_free": false,
            "is_visible_to_expat": true,
            "restricted_countries": [],
            "first_year_total": "18000.00"
          }
        ],
        "total_benefits": 1,
        "total_benefits_by_application": [
          {
            "name": "assignment",
            "label": "Assignment",
            "count": 1
          }
        ],
        "total_amount": "1500.00",
        "created_at": "2026-04-25T08:42:33+00:00",
        "assignment_client_id": 77,
        "assignment_start_date": "2026-05-01"
      }
    ],
    "filters": []
  }
}

GET /v1/benefits-packages/{packageId}

Return one benefit package by ID.

Headers

Header	Required	Value
Authorization	Yes	Bearer {{ACCESS_TOKEN}}
Accept	Yes	application/json

Path Parameters

Parameter	Type	Required	Description
packageId	number	Yes	Benefit package identifier.

Example Request

curl -X GET "{{BASE_URL}}/v1/benefits-packages/{{PACKAGE_ID}}" \
  -H "Authorization: Bearer {{ACCESS_TOKEN}}" \
  -H "Accept: application/json"

Success Response (200)

{
  "package": {
    "id": 49,
    "name": "Relocation Core Package",
    "assignment_id": 378,
    "status": "approved",
    "currency": "EUR",
    "local_currency": "EUR",
    "is_visible_to_expat": true,
    "planned_start_date": "2026-05-01",
    "planned_end_date": "2026-09-01",
    "actual_end_date": null,
    "archived_at": null,
    "benefits": [
      {
        "id": 63,
        "benefit_id": "3fddf23f-0e3d-4d6a-bc2c-c4f79fe7025c",
        "type": "benefit",
        "name": "Housing Allowance",
        "status": "active",
        "amount": "1500.00",
        "amount_type": "fixed",
        "currency": "EUR",
        "frequency": "monthly",
        "frequency_label": "Monthly",
        "beneficiary_type": "expat",
        "applies": "assignment",
        "payment_method": "payroll",
        "tax_free": false,
        "is_visible_to_expat": true,
        "restricted_countries": [],
        "first_year_total": "18000.00"
      }
    ],
    "total_benefits": 1,
    "total_benefits_by_application": [
      {
        "name": "assignment",
        "label": "Assignment",
        "count": 1
      }
    ],
    "total_amount": "1500.00",
    "created_at": "2026-04-25T08:42:33+00:00",
    "assignment_client_id": 77,
    "assignment_start_date": "2026-05-01",
    "approvals": []
  }
}