Skip to content

API reference

My benefits

A person's own benefits: what they have, their flexible budget and choices with the tax limits (Me keys read; choosing is in the app).

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

My benefits#

POST/v1/benefits/me.getRead

Your benefits: what the company gives you, your flexible budget (this year, used, left), what you may choose with each country's tax-free limit (estimated; your payroll provider applies the final tax), and whether you can change them now (your new-joiner window or open enrolment) or from when. Change them with benefits_me_choose, in the app.

Who can call it
Me key anyone
MCP tool
benefits_me_get on My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

11 fields
  • person_idstring | nullrequired
  • todaystringrequired
  • currencystringrequired
  • entityobject | nullrequired
    3 fields
    • idstringrequired
    • namestringrequired
    • countrystringrequired
  • windowobjectrequired
    6 fields
    • openbooleanrequired
    • kind"joiner" | "open_enrolment"required
    • closesstring | nullrequired
    • effectivestring | nullrequired

      Choices made now apply from this day.

    • next_opensstring | nullrequired
    • next_effectivestring | nullrequired
  • haveobject[]required

    Benefits the company gives with no choice to make.

    16 fields
    • idstringrequired
    • typestring (enum)required

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

    • namestringrequired
    • providerstring | nullrequired
    • funding"employer" | "flex" | "sacrifice" | "employee"required
    • unit"day" | "month" | "year"required
    • onbooleanrequired

      Has it from the day choices apply (or today when no window is open).

    • amount_centsintegerrequired

      Per unit, as chosen (or the company's amount).

    • default_centsintegerrequired

      What the amount is prefilled with when switched on: the company's amount, the tax-free limit, or an even share of the budget.

    • max_centsinteger | nullrequired
    • fixedbooleanrequired

      The amount is the company's (employer, employee contribution): not the person's to change.

    • factornumberrequired

      Multiply the amount per unit by this (and round) for its cost in the budget year from the day choices apply: the same formula payroll's estimate uses.

    • year_centsintegerrequired

      Its estimated cost in the budget year from the day choices apply.

    • fromstring | nullrequired

      Since when it is on (null: off, or by default).

    • limitobject | nullrequired

      The country's tax-free limit (null: taxable as pay unless the payroll provider says otherwise).

      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).

    • over_limitbooleanrequired

      The amount is above the tax-free limit: the excess is taxed as pay (estimated).

  • choicesobject[]required

    Benefits the person switches on or off and sets an amount for.

    16 fields
    • idstringrequired
    • typestring (enum)required

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

    • namestringrequired
    • providerstring | nullrequired
    • funding"employer" | "flex" | "sacrifice" | "employee"required
    • unit"day" | "month" | "year"required
    • onbooleanrequired

      Has it from the day choices apply (or today when no window is open).

    • amount_centsintegerrequired

      Per unit, as chosen (or the company's amount).

    • default_centsintegerrequired

      What the amount is prefilled with when switched on: the company's amount, the tax-free limit, or an even share of the budget.

    • max_centsinteger | nullrequired
    • fixedbooleanrequired

      The amount is the company's (employer, employee contribution): not the person's to change.

    • factornumberrequired

      Multiply the amount per unit by this (and round) for its cost in the budget year from the day choices apply: the same formula payroll's estimate uses.

    • year_centsintegerrequired

      Its estimated cost in the budget year from the day choices apply.

    • fromstring | nullrequired

      Since when it is on (null: off, or by default).

    • limitobject | nullrequired

      The country's tax-free limit (null: taxable as pay unless the payroll provider says otherwise).

      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).

    • over_limitbooleanrequired

      The amount is above the tax-free limit: the excess is taxed as pay (estimated).

  • budgetobject | nullrequired

    The flexible budget (null: no plan at the person's entity).

    7 fields
    • yearintegerrequired
    • total_centsintegerrequired
    • spent_before_centsintegerrequired

      Already used this year before the day choices apply.

    • chosen_centsintegerrequired

      Used in the year in all, with the current choices.

    • left_centsintegerrequired
    • proratedbooleanrequired
    • unspent"lapse" | "carry" | "cash"required
  • sacrificeobject | nullrequired
    4 fields
    • cap_centsintegerrequired
    • chosen_centsintegerrequired
    • in_kind_cap_percentnumber | nullrequired

      The country's cap on pay in kind (ES 30 %).

    • in_kind_cap_centsinteger | nullrequired

      That cap as an amount a year, from the person's pay (their own data).

  • untaxed_centsintegerrequired

    Estimated: the yearly amount moved out of taxable pay by salary sacrifice within tax-free limits (A4b; never a net-pay figure).

  • suggestionstring[]required

    Benefit ids most people at the company chose (only when at least 10 chose; nobody named).

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/benefits/me.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "person_id": "p2",
    "today": "2026-11-13",
    "currency": "EUR",
    "entity": {
      "id": "e1",
      "name": "Acme Lda",
      "country": "PT"
    },
    "window": {
      "open": true,
      "kind": "joiner",
      "closes": "2026-12-01",
      "effective": "2026-11-02",
      "next_opens": null,
      "next_effective": null
    },
    "have": [
      {
        "id": "b1",
        "type": "meal",
        "name": "Meal allowance on a meal card",
        "provider": null,
        "funding": "employer",
        "unit": "day",
        "on": true,
        "amount_cents": 1046,
        "default_cents": 1046,
        "max_cents": null,
        "fixed": true,
        "factor": 41.3,
        "year_cents": 43200,
        "from": null,
        "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
        },
        "over_limit": false
      }
    ],
    "choices": [
      {
        "id": "b2",
        "type": "childcare",
        "name": "Childcare vouchers",
        "provider": null,
        "funding": "flex",
        "unit": "month",
        "on": true,
        "amount_cents": 10000,
        "default_cents": 3750,
        "max_cents": null,
        "fixed": false,
        "factor": 1.966667,
        "year_cents": 19667,
        "from": "2026-11-02",
        "limit": null,
        "over_limit": false
      }
    ],
    "budget": {
      "year": 2026,
      "total_cents": 29500,
      "spent_before_cents": 0,
      "chosen_cents": 19667,
      "left_cents": 9833,
      "prorated": true,
      "unspent": "lapse"
    },
    "sacrifice": null,
    "untaxed_cents": 0,
    "suggestion": []
  }
}

Choose my benefits#

POST/v1/benefits/me.chooseWrite

Sets your benefit choices while your window is open (new joiner, or open enrolment): for each benefit_id from benefits_me_get's choices, on and, for flexible and salary-sacrifice benefits, amount_cents per unit (default: the prefilled amount). Choices apply from the window's day; the flexible total must fit your budget and salary sacrifice the plan's cap. Use dry_run to see the result first. Only for yourself, in the app.

Who can call it
Me key anyone
MCP tool
benefits_me_choose on My Workplace
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • choicesobject[]required

    1–100 items.

    3 fields
    • benefit_idstringrequired

      1–64 characters.

    • onbooleanrequired
    • amount_centsinteger

      From 0 to 100000000.

Returns

11 fields
  • person_idstring | nullrequired
  • todaystringrequired
  • currencystringrequired
  • entityobject | nullrequired
    3 fields
    • idstringrequired
    • namestringrequired
    • countrystringrequired
  • windowobjectrequired
    6 fields
    • openbooleanrequired
    • kind"joiner" | "open_enrolment"required
    • closesstring | nullrequired
    • effectivestring | nullrequired

      Choices made now apply from this day.

    • next_opensstring | nullrequired
    • next_effectivestring | nullrequired
  • haveobject[]required

    Benefits the company gives with no choice to make.

    16 fields
    • idstringrequired
    • typestring (enum)required

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

    • namestringrequired
    • providerstring | nullrequired
    • funding"employer" | "flex" | "sacrifice" | "employee"required
    • unit"day" | "month" | "year"required
    • onbooleanrequired

      Has it from the day choices apply (or today when no window is open).

    • amount_centsintegerrequired

      Per unit, as chosen (or the company's amount).

    • default_centsintegerrequired

      What the amount is prefilled with when switched on: the company's amount, the tax-free limit, or an even share of the budget.

    • max_centsinteger | nullrequired
    • fixedbooleanrequired

      The amount is the company's (employer, employee contribution): not the person's to change.

    • factornumberrequired

      Multiply the amount per unit by this (and round) for its cost in the budget year from the day choices apply: the same formula payroll's estimate uses.

    • year_centsintegerrequired

      Its estimated cost in the budget year from the day choices apply.

    • fromstring | nullrequired

      Since when it is on (null: off, or by default).

    • limitobject | nullrequired

      The country's tax-free limit (null: taxable as pay unless the payroll provider says otherwise).

      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).

    • over_limitbooleanrequired

      The amount is above the tax-free limit: the excess is taxed as pay (estimated).

  • choicesobject[]required

    Benefits the person switches on or off and sets an amount for.

    16 fields
    • idstringrequired
    • typestring (enum)required

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

    • namestringrequired
    • providerstring | nullrequired
    • funding"employer" | "flex" | "sacrifice" | "employee"required
    • unit"day" | "month" | "year"required
    • onbooleanrequired

      Has it from the day choices apply (or today when no window is open).

    • amount_centsintegerrequired

      Per unit, as chosen (or the company's amount).

    • default_centsintegerrequired

      What the amount is prefilled with when switched on: the company's amount, the tax-free limit, or an even share of the budget.

    • max_centsinteger | nullrequired
    • fixedbooleanrequired

      The amount is the company's (employer, employee contribution): not the person's to change.

    • factornumberrequired

      Multiply the amount per unit by this (and round) for its cost in the budget year from the day choices apply: the same formula payroll's estimate uses.

    • year_centsintegerrequired

      Its estimated cost in the budget year from the day choices apply.

    • fromstring | nullrequired

      Since when it is on (null: off, or by default).

    • limitobject | nullrequired

      The country's tax-free limit (null: taxable as pay unless the payroll provider says otherwise).

      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).

    • over_limitbooleanrequired

      The amount is above the tax-free limit: the excess is taxed as pay (estimated).

  • budgetobject | nullrequired

    The flexible budget (null: no plan at the person's entity).

    7 fields
    • yearintegerrequired
    • total_centsintegerrequired
    • spent_before_centsintegerrequired

      Already used this year before the day choices apply.

    • chosen_centsintegerrequired

      Used in the year in all, with the current choices.

    • left_centsintegerrequired
    • proratedbooleanrequired
    • unspent"lapse" | "carry" | "cash"required
  • sacrificeobject | nullrequired
    4 fields
    • cap_centsintegerrequired
    • chosen_centsintegerrequired
    • in_kind_cap_percentnumber | nullrequired

      The country's cap on pay in kind (ES 30 %).

    • in_kind_cap_centsinteger | nullrequired

      That cap as an amount a year, from the person's pay (their own data).

  • untaxed_centsintegerrequired

    Estimated: the yearly amount moved out of taxable pay by salary sacrifice within tax-free limits (A4b; never a net-pay figure).

  • suggestionstring[]required

    Benefit ids most people at the company chose (only when at least 10 chose; nobody named).

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/benefits/me.choose \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "choices": [
    {
      "benefit_id": "b2",
      "on": true,
      "amount_cents": 10000
    },
    {
      "benefit_id": "b3",
      "on": false
    }
  ]
}'
Response
{
  "data": {
    "person_id": "p2",
    "today": "2026-11-13",
    "currency": "EUR",
    "entity": {
      "id": "e1",
      "name": "Acme Lda",
      "country": "PT"
    },
    "window": {
      "open": true,
      "kind": "joiner",
      "closes": "2026-12-01",
      "effective": "2026-11-02",
      "next_opens": null,
      "next_effective": null
    },
    "have": [
      {
        "id": "b1",
        "type": "meal",
        "name": "Meal allowance on a meal card",
        "provider": null,
        "funding": "employer",
        "unit": "day",
        "on": true,
        "amount_cents": 1046,
        "default_cents": 1046,
        "max_cents": null,
        "fixed": true,
        "factor": 41.3,
        "year_cents": 43200,
        "from": null,
        "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
        },
        "over_limit": false
      }
    ],
    "choices": [
      {
        "id": "b2",
        "type": "childcare",
        "name": "Childcare vouchers",
        "provider": null,
        "funding": "flex",
        "unit": "month",
        "on": true,
        "amount_cents": 10000,
        "default_cents": 3750,
        "max_cents": null,
        "fixed": false,
        "factor": 1.966667,
        "year_cents": 19667,
        "from": "2026-11-02",
        "limit": null,
        "over_limit": false
      }
    ],
    "budget": {
      "year": 2026,
      "total_cents": 29500,
      "spent_before_cents": 0,
      "chosen_cents": 19667,
      "left_cents": 9833,
      "prorated": true,
      "unspent": "lapse"
    },
    "sacrifice": null,
    "untaxed_cents": 0,
    "suggestion": []
  }
}

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

Developer docs