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_geton My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
11 fields
person_idstring | nullrequiredtodaystringrequiredcurrencystringrequiredentityobject | nullrequired3 fields
idstringrequirednamestringrequiredcountrystringrequired
windowobjectrequired6 fields
openbooleanrequiredkind"joiner" | "open_enrolment"requiredclosesstring | nullrequiredeffectivestring | nullrequiredChoices made now apply from this day.
next_opensstring | nullrequirednext_effectivestring | nullrequired
haveobject[]requiredBenefits the company gives with no choice to make.
16 fields
idstringrequiredtypestring (enum)requiredOne of:
meal,health,dental,life,pension,childcare,transport,education,wellbeing,remote_work,mobility,other.namestringrequiredproviderstring | nullrequiredfunding"employer" | "flex" | "sacrifice" | "employee"requiredunit"day" | "month" | "year"requiredonbooleanrequiredHas it from the day choices apply (or today when no window is open).
amount_centsintegerrequiredPer unit, as chosen (or the company's amount).
default_centsintegerrequiredWhat 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 | nullrequiredfixedbooleanrequiredThe amount is the company's (employer, employee contribution): not the person's to change.
factornumberrequiredMultiply 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_centsintegerrequiredIts estimated cost in the budget year from the day choices apply.
fromstring | nullrequiredSince when it is on (null: off, or by default).
limitobject | nullrequiredThe country's tax-free limit (null: taxable as pay unless the payroll provider says otherwise).
11 fields
rule_idstringrequiredlabelstringrequiredcentsinteger | nullrequiredThe tax-free limit per unit; null: tax-free with no cap when the conditions are met.
unit"day" | "month" | "year"requiredmode"excess_taxed" | "cliff" | "employer_pool"requiredconditionsstring[]requiredlawstringrequiredsource_urlstringrequiredchecked_onstringrequiredstatus"enacted" | "to_verify"requiredto_verify: still to be checked against the official text.
lost_by_salary_swapbooleanrequiredSalary sacrifice loses this exemption (the country requires it not to replace pay).
over_limitbooleanrequiredThe amount is above the tax-free limit: the excess is taxed as pay (estimated).
choicesobject[]requiredBenefits the person switches on or off and sets an amount for.
16 fields
idstringrequiredtypestring (enum)requiredOne of:
meal,health,dental,life,pension,childcare,transport,education,wellbeing,remote_work,mobility,other.namestringrequiredproviderstring | nullrequiredfunding"employer" | "flex" | "sacrifice" | "employee"requiredunit"day" | "month" | "year"requiredonbooleanrequiredHas it from the day choices apply (or today when no window is open).
amount_centsintegerrequiredPer unit, as chosen (or the company's amount).
default_centsintegerrequiredWhat 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 | nullrequiredfixedbooleanrequiredThe amount is the company's (employer, employee contribution): not the person's to change.
factornumberrequiredMultiply 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_centsintegerrequiredIts estimated cost in the budget year from the day choices apply.
fromstring | nullrequiredSince when it is on (null: off, or by default).
limitobject | nullrequiredThe country's tax-free limit (null: taxable as pay unless the payroll provider says otherwise).
11 fields
rule_idstringrequiredlabelstringrequiredcentsinteger | nullrequiredThe tax-free limit per unit; null: tax-free with no cap when the conditions are met.
unit"day" | "month" | "year"requiredmode"excess_taxed" | "cliff" | "employer_pool"requiredconditionsstring[]requiredlawstringrequiredsource_urlstringrequiredchecked_onstringrequiredstatus"enacted" | "to_verify"requiredto_verify: still to be checked against the official text.
lost_by_salary_swapbooleanrequiredSalary sacrifice loses this exemption (the country requires it not to replace pay).
over_limitbooleanrequiredThe amount is above the tax-free limit: the excess is taxed as pay (estimated).
budgetobject | nullrequiredThe flexible budget (null: no plan at the person's entity).
7 fields
yearintegerrequiredtotal_centsintegerrequiredspent_before_centsintegerrequiredAlready used this year before the day choices apply.
chosen_centsintegerrequiredUsed in the year in all, with the current choices.
left_centsintegerrequiredproratedbooleanrequiredunspent"lapse" | "carry" | "cash"required
sacrificeobject | nullrequired4 fields
cap_centsintegerrequiredchosen_centsintegerrequiredin_kind_cap_percentnumber | nullrequiredThe country's cap on pay in kind (ES 30 %).
in_kind_cap_centsinteger | nullrequiredThat cap as an amount a year, from the person's pay (their own data).
untaxed_centsintegerrequiredEstimated: the yearly amount moved out of taxable pay by salary sacrifice within tax-free limits (A4b; never a net-pay figure).
suggestionstring[]requiredBenefit 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 https://api.bizisy.com/v1/benefits/me.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/benefits/me.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/benefits/me.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_chooseon My Workplace- Preview
?dry_run=trueruns 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[]required1–100 items.
3 fields
benefit_idstringrequired1–64 characters.
onbooleanrequiredamount_centsintegerFrom 0 to 100000000.
Returns
11 fields
person_idstring | nullrequiredtodaystringrequiredcurrencystringrequiredentityobject | nullrequired3 fields
idstringrequirednamestringrequiredcountrystringrequired
windowobjectrequired6 fields
openbooleanrequiredkind"joiner" | "open_enrolment"requiredclosesstring | nullrequiredeffectivestring | nullrequiredChoices made now apply from this day.
next_opensstring | nullrequirednext_effectivestring | nullrequired
haveobject[]requiredBenefits the company gives with no choice to make.
16 fields
idstringrequiredtypestring (enum)requiredOne of:
meal,health,dental,life,pension,childcare,transport,education,wellbeing,remote_work,mobility,other.namestringrequiredproviderstring | nullrequiredfunding"employer" | "flex" | "sacrifice" | "employee"requiredunit"day" | "month" | "year"requiredonbooleanrequiredHas it from the day choices apply (or today when no window is open).
amount_centsintegerrequiredPer unit, as chosen (or the company's amount).
default_centsintegerrequiredWhat 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 | nullrequiredfixedbooleanrequiredThe amount is the company's (employer, employee contribution): not the person's to change.
factornumberrequiredMultiply 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_centsintegerrequiredIts estimated cost in the budget year from the day choices apply.
fromstring | nullrequiredSince when it is on (null: off, or by default).
limitobject | nullrequiredThe country's tax-free limit (null: taxable as pay unless the payroll provider says otherwise).
11 fields
rule_idstringrequiredlabelstringrequiredcentsinteger | nullrequiredThe tax-free limit per unit; null: tax-free with no cap when the conditions are met.
unit"day" | "month" | "year"requiredmode"excess_taxed" | "cliff" | "employer_pool"requiredconditionsstring[]requiredlawstringrequiredsource_urlstringrequiredchecked_onstringrequiredstatus"enacted" | "to_verify"requiredto_verify: still to be checked against the official text.
lost_by_salary_swapbooleanrequiredSalary sacrifice loses this exemption (the country requires it not to replace pay).
over_limitbooleanrequiredThe amount is above the tax-free limit: the excess is taxed as pay (estimated).
choicesobject[]requiredBenefits the person switches on or off and sets an amount for.
16 fields
idstringrequiredtypestring (enum)requiredOne of:
meal,health,dental,life,pension,childcare,transport,education,wellbeing,remote_work,mobility,other.namestringrequiredproviderstring | nullrequiredfunding"employer" | "flex" | "sacrifice" | "employee"requiredunit"day" | "month" | "year"requiredonbooleanrequiredHas it from the day choices apply (or today when no window is open).
amount_centsintegerrequiredPer unit, as chosen (or the company's amount).
default_centsintegerrequiredWhat 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 | nullrequiredfixedbooleanrequiredThe amount is the company's (employer, employee contribution): not the person's to change.
factornumberrequiredMultiply 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_centsintegerrequiredIts estimated cost in the budget year from the day choices apply.
fromstring | nullrequiredSince when it is on (null: off, or by default).
limitobject | nullrequiredThe country's tax-free limit (null: taxable as pay unless the payroll provider says otherwise).
11 fields
rule_idstringrequiredlabelstringrequiredcentsinteger | nullrequiredThe tax-free limit per unit; null: tax-free with no cap when the conditions are met.
unit"day" | "month" | "year"requiredmode"excess_taxed" | "cliff" | "employer_pool"requiredconditionsstring[]requiredlawstringrequiredsource_urlstringrequiredchecked_onstringrequiredstatus"enacted" | "to_verify"requiredto_verify: still to be checked against the official text.
lost_by_salary_swapbooleanrequiredSalary sacrifice loses this exemption (the country requires it not to replace pay).
over_limitbooleanrequiredThe amount is above the tax-free limit: the excess is taxed as pay (estimated).
budgetobject | nullrequiredThe flexible budget (null: no plan at the person's entity).
7 fields
yearintegerrequiredtotal_centsintegerrequiredspent_before_centsintegerrequiredAlready used this year before the day choices apply.
chosen_centsintegerrequiredUsed in the year in all, with the current choices.
left_centsintegerrequiredproratedbooleanrequiredunspent"lapse" | "carry" | "cash"required
sacrificeobject | nullrequired4 fields
cap_centsintegerrequiredchosen_centsintegerrequiredin_kind_cap_percentnumber | nullrequiredThe country's cap on pay in kind (ES 30 %).
in_kind_cap_centsinteger | nullrequiredThat cap as an amount a year, from the person's pay (their own data).
untaxed_centsintegerrequiredEstimated: the yearly amount moved out of taxable pay by salary sacrifice within tax-free limits (A4b; never a net-pay figure).
suggestionstring[]requiredBenefit 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 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
}
]
}'const res = await fetch('https://api.bizisy.com/v1/benefits/me.choose', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"choices": [
{
"benefit_id": "b2",
"on": true,
"amount_cents": 10000
},
{
"benefit_id": "b3",
"on": false
}
]
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/benefits/me.choose",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"choices": [
{
"benefit_id": "b2",
"on": True,
"amount_cents": 10000,
},
{
"benefit_id": "b3",
"on": False,
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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.