Skip to content

API reference

Benefits

The benefits catalogue with each country's tax limits (add the usual ones per country), flexible plans per legal entity, enrolment windows, settings, and who has which benefit (in the app only).

14 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.

List benefits#

POST/v1/benefits/catalogue.listRead

The company's benefits catalogue: type, who pays, amount per unit, which legal entities offer it, who is eligible, and each country's tax-free limit with its source (estimated; the payroll provider applies the final tax). Archived ones only with archived true. People enrolled and this month's cost only for owners, admins and HR in the app. Owners, admins and HR.

Who can call it
Manage key owner admin hr
MCP tool
benefits_catalogue_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • archivedboolean

    true: only archived benefits.

Returns

  • itemsobject[]required
    21 fields
    • idstringrequired
    • typestring (enum)required

      One of: meal, health, dental, life, pension, childcare, transport, education, wellbeing, remote_work, mobility, other.

    • namestringrequired
    • providerstring | nullrequired
    • entity_idsstring[]required
    • funding"employer" | "flex" | "sacrifice" | "employee"required
    • variant"cash" | "card"required
    • amount_centsintegerrequired

      Per unit: what the company gives (employer), the default a person may change (flex, sacrifice; 0: the person picks), or the person's contribution (employee).

    • unit"day" | "month" | "year"required
    • max_centsinteger | nullrequired
    • enrolment"automatic" | "opt_in" | "opt_out"required
    • group_idstring | nullrequired
    • wait_daysintegerrequired
    • codesobjectrequired
    • codes_taxableobjectrequired
    • archivedbooleanrequired
    • limitsobject[]required

      The tax-free limit at each offering entity's country today (null: taxable as pay unless your payroll provider says otherwise).

      3 fields
      • entity_idstringrequired
      • countrystringrequired
      • limitobject | nullrequired
        11 fields
        • rule_idstringrequired
        • labelstringrequired
        • centsinteger | nullrequired

          The tax-free limit per unit; null: tax-free with no cap when the conditions are met.

        • unit"day" | "month" | "year"required
        • mode"excess_taxed" | "cliff" | "employer_pool"required
        • conditionsstring[]required
        • lawstringrequired
        • source_urlstringrequired
        • checked_onstringrequired
        • status"enacted" | "to_verify"required

          to_verify: still to be checked against the official text.

        • lost_by_salary_swapbooleanrequired

          Salary sacrifice loses this exemption (the country requires it not to replace pay).

    • enrolledinteger | nullrequired

      People who have it today (owners, admins and HR in the app; null otherwise).

    • month_cost_centsinteger | nullrequired

      Estimated cost this month (owners, admins and HR in the app; null otherwise).

    • created_atstringrequired
    • updated_atstringrequired
  • totalintegerrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/benefits/catalogue.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"archived":true}'
Response
{
  "data": {
    "items": [
      {
        "id": "b1",
        "type": "meal",
        "name": "Meal allowance on a meal card",
        "provider": null,
        "entity_ids": [
          "e1"
        ],
        "funding": "employer",
        "variant": "card",
        "amount_cents": 1046,
        "unit": "day",
        "max_cents": null,
        "enrolment": "automatic",
        "group_id": null,
        "wait_days": 0,
        "codes": {
          "datev": "4100"
        },
        "codes_taxable": {},
        "archived": false,
        "limits": [
          {
            "entity_id": "e1",
            "country": "PT",
            "limit": {
              "rule_id": "pt.meal_card.2026",
              "label": "Meal allowance on a meal card",
              "cents": 1046,
              "unit": "day",
              "mode": "excess_taxed",
              "conditions": [],
              "law": "CIRS, art. 2.º, n.º 3, b), 2); Portaria 51-B/2026/1",
              "source_url": "https://info.portaldasfinancas.gov.pt/",
              "checked_on": "2026-11-14",
              "status": "to_verify",
              "lost_by_salary_swap": false
            }
          }
        ],
        "enrolled": 12,
        "month_cost_cents": 263592,
        "created_at": "2026-11-13T10:00:00.000Z",
        "updated_at": "2026-11-13T10:00:00.000Z"
      }
    ],
    "total": 1
  }
}

Add a benefit#

POST/v1/benefits/catalogue.createWrite

Adds a benefit to the catalogue. Only type is required: the country pack prefills the amount at the tax-free limit ("a Portuguese meal card is one tap and one amount"), the entities, who pays and how people get it. Up to 100 per company. Supports dry_run (the preview shows every default). Owners, admins and HR.

Who can call it
Manage key owner admin hr
MCP tool
benefits_catalogue_create on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • typestring (enum)required

    meal, health, dental, life, pension, childcare, transport, education, wellbeing, remote_work, mobility or other.

    One of: meal, health, dental, life, pension, childcare, transport, education, wellbeing, remote_work, mobility, other.

  • namestring

    Shown to people. Default: from the type and provider ("Meal card · Edenred").

    1–80 characters.

  • providerstring | null

    Who provides it (free text).

    1–80 characters.

  • entity_idsstring[]

    Legal entities that offer it (org_entities_list). Default: every entity whose country has a tax rule for the type, else all.

    1–64 characters. 1–50 items.

  • funding"employer" | "flex" | "sacrifice" | "employee"

    employer (the company pays, no choice), flex (from the person's flexible budget), sacrifice (from gross pay), employee (the person pays, deducted). Default per type: meal and health employer; education, childcare, transport flex.

  • variant"cash" | "card"

    Meal allowance only: card (default) or cash; Portugal's limits differ.

  • amount_centsinteger

    Per unit, in cents. Default: the country's tax-free limit for the type when it has one.

    From 0 to 100000000.

  • unit"day" | "month" | "year"

    day (per day worked), month or year. Default: the limit's unit (meal: day), else month.

  • max_centsinteger | null

    Flex and sacrifice: the most a person may choose per unit.

    From 0 to 100000000.

  • enrolment"automatic" | "opt_in" | "opt_out"

    automatic: everyone eligible has it; opt_in: people switch it on; opt_out: on unless people switch it off. Default: automatic for employer, else opt_in.

  • group_idstring | null

    Only people in this saved group (org_groups_list); null: everyone at the entities.

    1–64 characters.

  • wait_daysinteger

    Days after the start before someone is eligible. Default 0.

    From 0 to 730.

  • codesobject

    Payroll item codes per export (datev, brightpay, generic, lexware, sage50, silae, staffology, xero_payroll…) for the tax-free part, or the whole when the country does not split it.

  • codes_taxableobject

    Payroll item codes for the taxable part, when the country splits it.

Returns

21 fields
  • idstringrequired
  • typestring (enum)required

    One of: meal, health, dental, life, pension, childcare, transport, education, wellbeing, remote_work, mobility, other.

  • namestringrequired
  • providerstring | nullrequired
  • entity_idsstring[]required
  • funding"employer" | "flex" | "sacrifice" | "employee"required
  • variant"cash" | "card"required
  • amount_centsintegerrequired

    Per unit: what the company gives (employer), the default a person may change (flex, sacrifice; 0: the person picks), or the person's contribution (employee).

  • unit"day" | "month" | "year"required
  • max_centsinteger | nullrequired
  • enrolment"automatic" | "opt_in" | "opt_out"required
  • group_idstring | nullrequired
  • wait_daysintegerrequired
  • codesobjectrequired
  • codes_taxableobjectrequired
  • archivedbooleanrequired
  • limitsobject[]required

    The tax-free limit at each offering entity's country today (null: taxable as pay unless your payroll provider says otherwise).

    3 fields
    • entity_idstringrequired
    • countrystringrequired
    • limitobject | nullrequired
      11 fields
      • rule_idstringrequired
      • labelstringrequired
      • centsinteger | nullrequired

        The tax-free limit per unit; null: tax-free with no cap when the conditions are met.

      • unit"day" | "month" | "year"required
      • mode"excess_taxed" | "cliff" | "employer_pool"required
      • conditionsstring[]required
      • lawstringrequired
      • source_urlstringrequired
      • checked_onstringrequired
      • status"enacted" | "to_verify"required

        to_verify: still to be checked against the official text.

      • lost_by_salary_swapbooleanrequired

        Salary sacrifice loses this exemption (the country requires it not to replace pay).

  • enrolledinteger | nullrequired

    People who have it today (owners, admins and HR in the app; null otherwise).

  • month_cost_centsinteger | nullrequired

    Estimated cost this month (owners, admins and HR in the app; null otherwise).

  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/benefits/catalogue.create \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "type": "health",
  "provider": "Médis",
  "funding": "flex",
  "amount_cents": 4000,
  "unit": "month",
  "entity_ids": [
    "e1"
  ],
  "group_id": "g1",
  "wait_days": 90,
  "codes": {
    "datev": "4200"
  }
}'
Response
{
  "data": {
    "id": "b1",
    "type": "health",
    "name": "Meal allowance on a meal card",
    "provider": "Médis",
    "entity_ids": [
      "e1"
    ],
    "funding": "flex",
    "variant": "card",
    "amount_cents": 4000,
    "unit": "month",
    "max_cents": null,
    "enrolment": "automatic",
    "group_id": null,
    "wait_days": 90,
    "codes": {
      "datev": "4100"
    },
    "codes_taxable": {},
    "archived": false,
    "limits": [
      {
        "entity_id": "e1",
        "country": "PT",
        "limit": {
          "rule_id": "pt.meal_card.2026",
          "label": "Meal allowance on a meal card",
          "cents": 1046,
          "unit": "day",
          "mode": "excess_taxed",
          "conditions": [],
          "law": "CIRS, art. 2.º, n.º 3, b), 2); Portaria 51-B/2026/1",
          "source_url": "https://info.portaldasfinancas.gov.pt/",
          "checked_on": "2026-11-14",
          "status": "to_verify",
          "lost_by_salary_swap": false
        }
      }
    ],
    "enrolled": null,
    "month_cost_cents": null,
    "created_at": "2026-11-13T10:00:00.000Z",
    "updated_at": "2026-11-13T10:00:00.000Z"
  }
}

Change a benefit#

POST/v1/benefits/catalogue.updateWrite

Changes a benefit: any field of benefits_catalogue_create. People's own choices keep their amounts; automatic benefits follow the new amount from today. Supports dry_run. Owners, admins and HR.

Who can call it
Manage key owner admin hr
MCP tool
benefits_catalogue_update on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • benefit_idstringrequired

    1–64 characters.

  • typestring (enum)

    One of: meal, health, dental, life, pension, childcare, transport, education, wellbeing, remote_work, mobility, other.

  • namestring

    Shown to people. Default: from the type and provider ("Meal card · Edenred").

    1–80 characters.

  • providerstring | null

    Who provides it (free text).

    1–80 characters.

  • entity_idsstring[]

    Legal entities that offer it (org_entities_list). Default: every entity whose country has a tax rule for the type, else all.

    1–64 characters. 1–50 items.

  • funding"employer" | "flex" | "sacrifice" | "employee"

    employer (the company pays, no choice), flex (from the person's flexible budget), sacrifice (from gross pay), employee (the person pays, deducted). Default per type: meal and health employer; education, childcare, transport flex.

  • variant"cash" | "card"

    Meal allowance only: card (default) or cash; Portugal's limits differ.

  • amount_centsinteger

    Per unit, in cents. Default: the country's tax-free limit for the type when it has one.

    From 0 to 100000000.

  • unit"day" | "month" | "year"

    day (per day worked), month or year. Default: the limit's unit (meal: day), else month.

  • max_centsinteger | null

    Flex and sacrifice: the most a person may choose per unit.

    From 0 to 100000000.

  • enrolment"automatic" | "opt_in" | "opt_out"

    automatic: everyone eligible has it; opt_in: people switch it on; opt_out: on unless people switch it off. Default: automatic for employer, else opt_in.

  • group_idstring | null

    Only people in this saved group (org_groups_list); null: everyone at the entities.

    1–64 characters.

  • wait_daysinteger

    Days after the start before someone is eligible. Default 0.

    From 0 to 730.

  • codesobject

    Payroll item codes per export (datev, brightpay, generic, lexware, sage50, silae, staffology, xero_payroll…) for the tax-free part, or the whole when the country does not split it.

  • codes_taxableobject

    Payroll item codes for the taxable part, when the country splits it.

Returns

21 fields
  • idstringrequired
  • typestring (enum)required

    One of: meal, health, dental, life, pension, childcare, transport, education, wellbeing, remote_work, mobility, other.

  • namestringrequired
  • providerstring | nullrequired
  • entity_idsstring[]required
  • funding"employer" | "flex" | "sacrifice" | "employee"required
  • variant"cash" | "card"required
  • amount_centsintegerrequired

    Per unit: what the company gives (employer), the default a person may change (flex, sacrifice; 0: the person picks), or the person's contribution (employee).

  • unit"day" | "month" | "year"required
  • max_centsinteger | nullrequired
  • enrolment"automatic" | "opt_in" | "opt_out"required
  • group_idstring | nullrequired
  • wait_daysintegerrequired
  • codesobjectrequired
  • codes_taxableobjectrequired
  • archivedbooleanrequired
  • limitsobject[]required

    The tax-free limit at each offering entity's country today (null: taxable as pay unless your payroll provider says otherwise).

    3 fields
    • entity_idstringrequired
    • countrystringrequired
    • limitobject | nullrequired
      11 fields
      • rule_idstringrequired
      • labelstringrequired
      • centsinteger | nullrequired

        The tax-free limit per unit; null: tax-free with no cap when the conditions are met.

      • unit"day" | "month" | "year"required
      • mode"excess_taxed" | "cliff" | "employer_pool"required
      • conditionsstring[]required
      • lawstringrequired
      • source_urlstringrequired
      • checked_onstringrequired
      • status"enacted" | "to_verify"required

        to_verify: still to be checked against the official text.

      • lost_by_salary_swapbooleanrequired

        Salary sacrifice loses this exemption (the country requires it not to replace pay).

  • enrolledinteger | nullrequired

    People who have it today (owners, admins and HR in the app; null otherwise).

  • month_cost_centsinteger | nullrequired

    Estimated cost this month (owners, admins and HR in the app; null otherwise).

  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/benefits/catalogue.update \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"benefit_id":"b1","amount_cents":900}'
Response
{
  "data": {
    "id": "b1",
    "type": "meal",
    "name": "Meal allowance on a meal card",
    "provider": null,
    "entity_ids": [
      "e1"
    ],
    "funding": "employer",
    "variant": "card",
    "amount_cents": 900,
    "unit": "day",
    "max_cents": null,
    "enrolment": "automatic",
    "group_id": null,
    "wait_days": 0,
    "codes": {
      "datev": "4100"
    },
    "codes_taxable": {},
    "archived": false,
    "limits": [
      {
        "entity_id": "e1",
        "country": "PT",
        "limit": {
          "rule_id": "pt.meal_card.2026",
          "label": "Meal allowance on a meal card",
          "cents": 1046,
          "unit": "day",
          "mode": "excess_taxed",
          "conditions": [],
          "law": "CIRS, art. 2.º, n.º 3, b), 2); Portaria 51-B/2026/1",
          "source_url": "https://info.portaldasfinancas.gov.pt/",
          "checked_on": "2026-11-14",
          "status": "to_verify",
          "lost_by_salary_swap": false
        }
      }
    ],
    "enrolled": null,
    "month_cost_cents": null,
    "created_at": "2026-11-13T10:00:00.000Z",
    "updated_at": "2026-11-13T10:00:00.000Z"
  }
}

Archive a benefit#

POST/v1/benefits/catalogue.archiveWrite

Archives a benefit (archived false brings it back): nobody has it from today, and payroll stops getting it. People's past choices stay. Supports dry_run. Owners, admins and HR.

Who can call it
Manage key owner admin hr
MCP tool
benefits_catalogue_archive on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • benefit_idstringrequired

    1–64 characters.

  • archivedboolean

    Default true.

Returns

21 fields
  • idstringrequired
  • typestring (enum)required

    One of: meal, health, dental, life, pension, childcare, transport, education, wellbeing, remote_work, mobility, other.

  • namestringrequired
  • providerstring | nullrequired
  • entity_idsstring[]required
  • funding"employer" | "flex" | "sacrifice" | "employee"required
  • variant"cash" | "card"required
  • amount_centsintegerrequired

    Per unit: what the company gives (employer), the default a person may change (flex, sacrifice; 0: the person picks), or the person's contribution (employee).

  • unit"day" | "month" | "year"required
  • max_centsinteger | nullrequired
  • enrolment"automatic" | "opt_in" | "opt_out"required
  • group_idstring | nullrequired
  • wait_daysintegerrequired
  • codesobjectrequired
  • codes_taxableobjectrequired
  • archivedbooleanrequired
  • limitsobject[]required

    The tax-free limit at each offering entity's country today (null: taxable as pay unless your payroll provider says otherwise).

    3 fields
    • entity_idstringrequired
    • countrystringrequired
    • limitobject | nullrequired
      11 fields
      • rule_idstringrequired
      • labelstringrequired
      • centsinteger | nullrequired

        The tax-free limit per unit; null: tax-free with no cap when the conditions are met.

      • unit"day" | "month" | "year"required
      • mode"excess_taxed" | "cliff" | "employer_pool"required
      • conditionsstring[]required
      • lawstringrequired
      • source_urlstringrequired
      • checked_onstringrequired
      • status"enacted" | "to_verify"required

        to_verify: still to be checked against the official text.

      • lost_by_salary_swapbooleanrequired

        Salary sacrifice loses this exemption (the country requires it not to replace pay).

  • enrolledinteger | nullrequired

    People who have it today (owners, admins and HR in the app; null otherwise).

  • month_cost_centsinteger | nullrequired

    Estimated cost this month (owners, admins and HR in the app; null otherwise).

  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/benefits/catalogue.archive \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"benefit_id":"b1","archived":false}'
Response
{
  "data": {
    "id": "b1",
    "type": "meal",
    "name": "Meal allowance on a meal card",
    "provider": null,
    "entity_ids": [
      "e1"
    ],
    "funding": "employer",
    "variant": "card",
    "amount_cents": 1046,
    "unit": "day",
    "max_cents": null,
    "enrolment": "automatic",
    "group_id": null,
    "wait_days": 0,
    "codes": {
      "datev": "4100"
    },
    "codes_taxable": {},
    "archived": false,
    "limits": [
      {
        "entity_id": "e1",
        "country": "PT",
        "limit": {
          "rule_id": "pt.meal_card.2026",
          "label": "Meal allowance on a meal card",
          "cents": 1046,
          "unit": "day",
          "mode": "excess_taxed",
          "conditions": [],
          "law": "CIRS, art. 2.º, n.º 3, b), 2); Portaria 51-B/2026/1",
          "source_url": "https://info.portaldasfinancas.gov.pt/",
          "checked_on": "2026-11-14",
          "status": "to_verify",
          "lost_by_salary_swap": false
        }
      }
    ],
    "enrolled": null,
    "month_cost_cents": null,
    "created_at": "2026-11-13T10:00:00.000Z",
    "updated_at": "2026-11-13T10:00:00.000Z"
  }
}

Add the usual benefits#

POST/v1/benefits/catalogue.add_usualWrite

Adds the benefits each country's tax rules make common, for the given legal entities (default: all): Portugal: a meal card at the tax-free limit (company paid) and childcare, training, transport and health as flexible choices; Spain: a restaurant card and health, transport, nursery and training as flexible choices. Types the entity already offers are skipped. Countries without rules get nothing (taxable as pay). Use dry_run to preview, then run it for real. Owners, admins and HR.

Who can call it
Manage key owner admin hr
MCP tool
benefits_catalogue_add_usual on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • entity_idsstring[]

    1–64 characters. Up to 50 items.

Returns

  • itemsobject[]required
    21 fields
    • idstringrequired
    • typestring (enum)required

      One of: meal, health, dental, life, pension, childcare, transport, education, wellbeing, remote_work, mobility, other.

    • namestringrequired
    • providerstring | nullrequired
    • entity_idsstring[]required
    • funding"employer" | "flex" | "sacrifice" | "employee"required
    • variant"cash" | "card"required
    • amount_centsintegerrequired

      Per unit: what the company gives (employer), the default a person may change (flex, sacrifice; 0: the person picks), or the person's contribution (employee).

    • unit"day" | "month" | "year"required
    • max_centsinteger | nullrequired
    • enrolment"automatic" | "opt_in" | "opt_out"required
    • group_idstring | nullrequired
    • wait_daysintegerrequired
    • codesobjectrequired
    • codes_taxableobjectrequired
    • archivedbooleanrequired
    • limitsobject[]required

      The tax-free limit at each offering entity's country today (null: taxable as pay unless your payroll provider says otherwise).

      3 fields
      • entity_idstringrequired
      • countrystringrequired
      • limitobject | nullrequired
        11 fields
        • rule_idstringrequired
        • labelstringrequired
        • centsinteger | nullrequired

          The tax-free limit per unit; null: tax-free with no cap when the conditions are met.

        • unit"day" | "month" | "year"required
        • mode"excess_taxed" | "cliff" | "employer_pool"required
        • conditionsstring[]required
        • lawstringrequired
        • source_urlstringrequired
        • checked_onstringrequired
        • status"enacted" | "to_verify"required

          to_verify: still to be checked against the official text.

        • lost_by_salary_swapbooleanrequired

          Salary sacrifice loses this exemption (the country requires it not to replace pay).

    • enrolledinteger | nullrequired

      People who have it today (owners, admins and HR in the app; null otherwise).

    • month_cost_centsinteger | nullrequired

      Estimated cost this month (owners, admins and HR in the app; null otherwise).

    • created_atstringrequired
    • updated_atstringrequired
  • skippedobject[]required
    3 fields
    • entity_idstringrequired
    • countrystringrequired
    • reasonstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/benefits/catalogue.add_usual \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"entity_ids":["e1"]}'
Response
{
  "data": {
    "items": [
      {
        "id": "b1",
        "type": "meal",
        "name": "Meal allowance on a meal card",
        "provider": null,
        "entity_ids": [
          "e1"
        ],
        "funding": "employer",
        "variant": "card",
        "amount_cents": 1046,
        "unit": "day",
        "max_cents": null,
        "enrolment": "automatic",
        "group_id": null,
        "wait_days": 0,
        "codes": {
          "datev": "4100"
        },
        "codes_taxable": {},
        "archived": false,
        "limits": [
          {
            "entity_id": "e1",
            "country": "PT",
            "limit": {
              "rule_id": "pt.meal_card.2026",
              "label": "Meal allowance on a meal card",
              "cents": 1046,
              "unit": "day",
              "mode": "excess_taxed",
              "conditions": [],
              "law": "CIRS, art. 2.º, n.º 3, b), 2); Portaria 51-B/2026/1",
              "source_url": "https://info.portaldasfinancas.gov.pt/",
              "checked_on": "2026-11-14",
              "status": "to_verify",
              "lost_by_salary_swap": false
            }
          }
        ],
        "enrolled": null,
        "month_cost_cents": null,
        "created_at": "2026-11-13T10:00:00.000Z",
        "updated_at": "2026-11-13T10:00:00.000Z"
      }
    ],
    "skipped": [
      {
        "entity_id": "e2",
        "country": "AT",
        "reason": "No tax rules for this country in Bizisy yet."
      }
    ]
  }
}

List flexible plans#

POST/v1/benefits/plans.listRead

The flexible plans: per legal entity, the budget the company funds (per month or year, prorated or not), salary sacrifice's yearly cap and what happens to unspent budget. Owners, admins and HR.

Who can call it
Manage key owner admin hr
MCP tool
benefits_plans_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • itemsobject[]required
    9 fields
    • idstringrequired
    • entity_idstringrequired
    • budget_centsintegerrequired
    • period"month" | "year"required
    • proratebooleanrequired
    • sacrifice_cap_centsinteger | nullrequired

      The most a person may swap from gross pay a year; null: no salary sacrifice.

    • unspent"lapse" | "carry" | "cash"required
    • archivedbooleanrequired
    • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/benefits/plans.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "items": [
      {
        "id": "pl1",
        "entity_id": "e1",
        "budget_cents": 180000,
        "period": "year",
        "prorate": true,
        "sacrifice_cap_cents": null,
        "unspent": "lapse",
        "archived": false,
        "updated_at": "2026-11-13T10:00:00.000Z"
      }
    ]
  }
}

Set a flexible plan#

POST/v1/benefits/plans.saveWrite

Sets the flexible plan of a legal entity (one per entity): budget_cents per period (month or year), prorate (joiners, leavers and part-time get a share; default true), sacrifice_cap_cents (the most a person may swap from gross pay a year; null: none) and unspent (lapse, the default; carry; cash, paid as taxable pay). Benefits with funding flex draw on the budget. Up to 20 plans. Supports dry_run. Owners, admins and HR.

Who can call it
Manage key owner admin hr
MCP tool
benefits_plans_save on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • entity_idstringrequired

    1–64 characters.

  • budget_centsintegerrequired

    From 0 to 100000000.

  • period"month" | "year"

    Default "year".

  • prorateboolean

    Default true.

  • sacrifice_cap_centsinteger | null

    From 0 to 100000000. Default null.

  • unspent"lapse" | "carry" | "cash"

    Default "lapse".

Returns

9 fields
  • idstringrequired
  • entity_idstringrequired
  • budget_centsintegerrequired
  • period"month" | "year"required
  • proratebooleanrequired
  • sacrifice_cap_centsinteger | nullrequired

    The most a person may swap from gross pay a year; null: no salary sacrifice.

  • unspent"lapse" | "carry" | "cash"required
  • archivedbooleanrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/benefits/plans.save \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "entity_id": "e1",
  "budget_cents": 15000,
  "period": "month",
  "prorate": false,
  "sacrifice_cap_cents": 300000,
  "unspent": "carry"
}'
Response
{
  "data": {
    "id": "pl1",
    "entity_id": "e1",
    "budget_cents": 15000,
    "period": "month",
    "prorate": false,
    "sacrifice_cap_cents": 300000,
    "unspent": "carry",
    "archived": false,
    "updated_at": "2026-11-13T10:00:00.000Z"
  }
}

End a flexible plan#

POST/v1/benefits/plans.archiveWrite

Ends an entity's flexible plan: flex benefits there have no budget from today (people's past choices stay). Supports dry_run. Owners, admins and HR.

Who can call it
Manage key owner admin hr
MCP tool
benefits_plans_archive on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • plan_idstringrequired

    1–64 characters.

Returns

9 fields
  • idstringrequired
  • entity_idstringrequired
  • budget_centsintegerrequired
  • period"month" | "year"required
  • proratebooleanrequired
  • sacrifice_cap_centsinteger | nullrequired

    The most a person may swap from gross pay a year; null: no salary sacrifice.

  • unspent"lapse" | "carry" | "cash"required
  • archivedbooleanrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/benefits/plans.archive \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"plan_id":"pl1"}'
Response
{
  "data": {
    "id": "pl1",
    "entity_id": "e1",
    "budget_cents": 180000,
    "period": "year",
    "prorate": true,
    "sacrifice_cap_cents": null,
    "unspent": "lapse",
    "archived": true,
    "updated_at": "2026-11-13T10:00:00.000Z"
  }
}

List enrolment windows#

POST/v1/benefits/windows.listRead

Open enrolment windows per legal entity: when they open and close and from when choices apply (upcoming, open or closed today). New joiners also get their own window from their first day (Settings → Benefits). Owners, admins and HR.

Who can call it
Manage key owner admin hr
MCP tool
benefits_windows_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • itemsobject[]required
    6 fields
    • idstringrequired
    • entity_idstringrequired
    • opensstringrequired
    • closesstringrequired
    • effectivestringrequired
    • state"upcoming" | "open" | "closed"required

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/benefits/windows.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "items": [
      {
        "id": "w1",
        "entity_id": "e1",
        "opens": "2026-12-01",
        "closes": "2026-12-31",
        "effective": "2027-01-01",
        "state": "upcoming"
      }
    ]
  }
}

Open enrolment#

POST/v1/benefits/windows.openWrite

Opens enrolment for legal entities: from opens (default today) to closes (default 30 days later); choices apply from effective (default the 1st of the month after closing). People without a choice see it on Home. One open window per entity at a time; up to 200 windows in all. Supports dry_run. Owners, admins and HR.

Who can call it
Manage key owner admin hr
MCP tool
benefits_windows_open on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • entity_idsstring[]required

    1–64 characters. 1–50 items.

  • opensstring

    Pattern ^\d{4}-\d{2}-\d{2}$.

  • closesstring

    Pattern ^\d{4}-\d{2}-\d{2}$.

  • effectivestring

    Pattern ^\d{4}-\d{2}-\d{2}$.

Returns

  • itemsobject[]required
    6 fields
    • idstringrequired
    • entity_idstringrequired
    • opensstringrequired
    • closesstringrequired
    • effectivestringrequired
    • state"upcoming" | "open" | "closed"required

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/benefits/windows.open \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "entity_ids": [
    "e1"
  ],
  "opens": "2026-12-01",
  "closes": "2026-12-31",
  "effective": "2027-01-01"
}'
Response
{
  "data": {
    "items": [
      {
        "id": "w1",
        "entity_id": "e1",
        "opens": "2026-12-01",
        "closes": "2026-12-31",
        "effective": "2027-01-01",
        "state": "upcoming"
      }
    ]
  }
}

Close enrolment#

POST/v1/benefits/windows.closeWrite

Closes an enrolment window today (an upcoming one is removed). Choices already made stay. Supports dry_run. Owners, admins and HR.

Who can call it
Manage key owner admin hr
MCP tool
benefits_windows_close on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • window_idstringrequired

    1–64 characters.

Returns

  • idstringrequired
  • removedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/benefits/windows.close \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"window_id":"w1"}'
Response
{
  "data": {
    "id": "w1",
    "removed": true
  }
}

Benefits settings#

POST/v1/benefits/settings.getRead

Settings → Benefits: how many days new joiners have to choose, and per country the conditions the company must meet for the tax-free treatment to hold (offered to everyone eligible, on top of pay, agreements). Owners, admins and HR.

Who can call it
Manage key owner admin hr
MCP tool
benefits_settings_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • joiner_daysintegerrequired
  • checklistobject[]required
    4 fields
    • countrystringrequired
    • entity_idsstring[]required
    • linesobject[]required

      What the company must do for the tax-free treatment to hold.

      2 fields
      • conditionstringrequired
      • textstringrequired
    • in_kind_cap_percentnumber | nullrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/benefits/settings.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "joiner_days": 30,
    "checklist": [
      {
        "country": "PT",
        "entity_ids": [
          "e1"
        ],
        "lines": [
          {
            "condition": "general_basis",
            "text": "Offer it to everyone eligible on the same terms, never to a chosen few."
          }
        ],
        "in_kind_cap_percent": null
      }
    ]
  }
}

Change benefits settings#

POST/v1/benefits/settings.updateWrite

Changes Settings → Benefits: joiner_days (1–90, default 30): how long a new joiner has to choose from their first day. Supports dry_run. Owners, admins and HR.

Who can call it
Manage key owner admin hr
MCP tool
benefits_settings_update on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • joiner_daysintegerrequired

    From 1 to 90.

Returns

  • joiner_daysintegerrequired
  • checklistobject[]required
    4 fields
    • countrystringrequired
    • entity_idsstring[]required
    • linesobject[]required

      What the company must do for the tax-free treatment to hold.

      2 fields
      • conditionstringrequired
      • textstringrequired
    • in_kind_cap_percentnumber | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/benefits/settings.update \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"joiner_days":30}'
Response
{
  "data": {
    "joiner_days": 30,
    "checklist": [
      {
        "country": "PT",
        "entity_ids": [
          "e1"
        ],
        "lines": [
          {
            "condition": "general_basis",
            "text": "Offer it to everyone eligible on the same terms, never to a chosen few."
          }
        ],
        "in_kind_cap_percent": null
      }
    ]
  }
}

Who has which benefit#

POST/v1/benefits/people.listRead

Per person employed today (optionally at one legal entity): the benefits they have and the amounts, their flexible budget used, and whether their window is open with nothing chosen yet. Pay data: owners, admins and HR.

Who can call it
Manage key owner admin hr
MCP tool
benefits_people_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • entity_idstring

    1–64 characters.

Returns

  • peopleobject[]required
    7 fields
    • person_idstringrequired
    • namestringrequired
    • entity_idstringrequired
    • benefitsobject[]required
      5 fields
      • idstringrequired
      • namestringrequired
      • amount_centsintegerrequired
      • unit"day" | "month" | "year"required
      • chosenbooleanrequired

        The person chose it (not given by default).

    • budgetobject | nullrequired
      2 fields
      • total_centsintegerrequired
      • chosen_centsintegerrequired
    • windowobjectrequired
      2 fields
      • openbooleanrequired
      • closesstring | nullrequired
    • not_chosenbooleanrequired

      Their window is open and they have made no choice in it yet.

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/benefits/people.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entity_id":"e1"}'
Response
{
  "data": {
    "people": [
      {
        "person_id": "p2",
        "name": "Bea Silva",
        "entity_id": "e1",
        "benefits": [
          {
            "id": "b1",
            "name": "Meal allowance on a meal card",
            "amount_cents": 1046,
            "unit": "day",
            "chosen": false
          }
        ],
        "budget": {
          "total_cents": 29500,
          "chosen_cents": 19667
        },
        "window": {
          "open": true,
          "closes": "2026-12-01"
        },
        "not_chosen": false
      }
    ]
  }
}

Something missing or wrong on this page? Write to hello@bizisy.com.

Developer docs