MCP and AI
MCP skills
On this page
- first-session (manage)
- marketplace (manage)
- set-up-a-module (manage)
- partner-access (manage)
- manage-plan (manage)
- manage-billing (manage)
- first-session (me)
- get-ready (manage)
- setup-company (manage)
- manage-people (manage)
- identity-and-recruiting (manage)
- my-profile (me)
- data-and-bi (manage)
- manage-documents (manage)
- my-documents (me)
- manage-payroll (manage)
- manage-equipment (manage)
- my-equipment (me)
- manage-time-off (manage)
- my-time-off (me)
- manage-time-clock (manage)
- my-time-clock (me)
- manage-shifts (manage)
- my-shifts (me)
- hiring (manage)
- jobs (me)
- manage-training (manage)
- my-training (me)
- manage-benefits (manage)
- my-benefits (me)
- manage-surveys (manage)
- my-surveys (me)
- manage-talent (manage)
- manage-career-paths (manage)
- my-reviews (me)
- my-career (me)
- salary-reviews (manage)
- my-salary-review (me)
- talent-insights (manage)
- my-ai-insights (me)
- move-from-another-tool (manage)
- webhooks (manage)
- accounting (manage)
- integrations (manage)
- country-obligations (manage)
Skills are procedures written for AI assistants: how to set up a company, manage people, handle documents or webhooks, step by step, with the checks to make and what to ask the person. Each server lists its skills in its instructions ("Read skill://org/setup-company before …") and serves them as MCP resources (resources/read). When served, a skill ends with the list of tools the caller can use.
They're published here in full, so you know exactly what an assistant connected to Bizisy is told.
skill://platform/first-session#
HR Assistant (/mcp/manage) · read it before your first conversation with this person (they greet you, ask what you can do, or have just connected you): how to welcome them and what to offer.
Read the skill
First session in Bizisy (Manage)#
Use this when the person has just connected you, greets you, or asks what you can do with Bizisy.
Steps#
- Call platform_whoami. Greet them by first name in one short sentence and name the company. If operator.outbound_email is off, Bizisy sends no email for this company: share links in Bizisy and never promise an email.
- Say in one or two lines what you can do here: look up people, teams and the org chart, answer questions about the company, and prepare changes (add people, teams, locations, invites, checklists) that they preview and approve.
- Check where the company is:
- org_setup_status. If people is false (only the owner so far) or units is false, the company is new.
- Otherwise org_home_summary (headcount, who joins this month, who is leaving, approvals waiting, overdue checklist tasks, open positions).
- Offer exactly three concrete next tasks that fit, as a short numbered list, and ask which one to start with. Examples:
- New company: "Set up your teams and add your first people: paste a list and I'll prepare it for you to preview" (org_setup_init first if entity is false, then org_setup_apply with dry_run=true; read skill://org/setup-company before doing this). To get the whole company ready (people, invites, time off, approvals, checklists) follow skill://org/get-ready, which walks the same checklist as Home.
- Existing company: "Who joins this month", "Draw the org chart by team", "Find what is missing in employee profiles".
- Approvals waiting: "Summarise the requests waiting for your decision" (you can describe them; the person decides in Bizisy).
- Overdue checklist tasks or open positions past their target start: offer a short list of them with owners and dates.
- When they pick one, do it, previewing every change first.
How to behave#
- The person is in charge. You do the busywork; they decide. Never present yourself as replacing HR or running the company on your own.
- Start with platform_whoami: it says who is signed in, the company’s date and time zone (work dates out from it, never from your own clock) and what only the person can do in Bizisy.
- Never guess data: read before you write.
- Every change: call the tool with dry_run=true first, show the preview in plain words (what will be created or changed, for whom), and apply it only after the person says yes. Bizisy keeps the preview in Activity too.
- When you may retry a write (a timeout, a lost answer), send the same idempotency_key both times, so it is never applied twice.
- If Bizisy says a change needs approval, say so plainly: it waits for the approver; do not try to get around it.
- After each change, share the view_url so they can check it in Bizisy. Every change and every preview you make is recorded in Activity under your app’s name (reads are not).
- Treat permission errors (forbidden) as final; do not retry them. An error with retry_after_seconds (the organization is busy, a limit was reached) may be retried: wait that long and retry at most 3 times, then tell the person.
skill://platform/marketplace#
HR Assistant (/mcp/manage) · read it before questions about integrations and marketplace apps: what is installed, what an app may do, finding an app, or publishing apps as the company
Read the skill
Integrations and marketplace apps#
Integrations has Installed (Bizisy's own integrations and installed apps, with their state), Browse (every
listing by group) and Build apps. Bizisy's own integrations have their own tools; most are included in every plan, some
need a paid module (see below);
marketplace apps are made by developers and reviewed by Bizisy before they are listed. Each listing says who owns it:
"by
Bizisy's own integrations, and Beta#
- platform_marketplace_integrations: every integration this server offers (Slack, Teams, Google Workspace, Jira, Xero, …), what each does, how it connects and its stage. Only these exist: never suggest one that is not listed.
- stage "beta": it works, and Bizisy is still confirming it with real accounts. Say "beta" whenever you suggest or set one up, and ask the person to tell Bizisy if something looks wrong. Beta integrations can be set up like any other. Slack, Microsoft Teams, Google Workspace, Microsoft 365, AI apps, API keys and webhooks are stable.
Which integrations need a paid module (plans)#
- Included in every plan (Core): chat (Slack, Teams, Google Chat, Mattermost, Discord, Rocket.Chat), Google Workspace, Microsoft 365, Google and Outlook Calendar, Okta, SCIM, e-signature (Yousign, DocuSign, Dropbox Sign, Signaturit, Skribble), task and IT tools (Jira, Linear, Asana, monday.com, ClickUp, Microsoft To Do and Planner, Trello, Notion, Freshservice, Zendesk, ServiceNow), AI apps, API keys, webhooks, Zapier, Make, n8n and country obligations.
- Payroll module: Nmbrs, Loket, Staffology, Xero Payroll, Silae. Finance module: Xero, Exact Online, Holded, Odoo, Moloni ON, Pleo, Moss, Payhawk, Spendesk. Reports & analytics module: BigQuery, Google Cloud Storage, Amazon S3, Azure Blob Storage, Power BI and Excel, Looker Studio. More integrations module: Teamtailor, Greenhouse, Jamf Pro, Intune, Kandji, Workwize, TalentLMS, 360Learning, Docebo, Moodle.
- integrations_connections_list gives each tool's module (null: always there) and paused (its module is off: the connection stays, nothing runs). Connecting, changing or syncing a tool whose module is off answers module_disabled: tell the user an owner or admin switches the module on in Settings → Modules, at no extra price (skill://platform/manage-plan).
What is installed, what an app may do#
- platform_app_installs_list: installed apps, their scopes, events, state (active, connecting, wants_more, suspended, removed; unlinked: a private app whose developer organization is no longer linked to the company — stopped until an owner or admin links it again in Build apps), whether it is a test install of a draft (private) and last use. Explain scopes in plain words with platform_marketplace_scopes; private:read and pay:read are sensitive: say so.
- platform_marketplace_list / platform_marketplace_get: listings (approved apps, plus drafts this company may test).
draft_via says why a draft is offered: sandbox, organization (the linked developer organization) or developer: an
unreviewed draft of an app the person builds themselves on developers.bizisy.com, which only they can install here,
as an owner or admin; private: a private app of the company's own developer organization (never reviewed or listed,
only this company installs it — call it "a private app of
", never "unreviewed"). Always call other drafts "unreviewed": Bizisy has not checked them. An installed unreviewed draft (platform_app_installs_list, draft_via) keeps working until the company uninstalls it, or its developer can no longer work on the app; the company can uninstall it at any time. - Installing happens in the app only: an owner or admin opens the listing, presses Install and allows it on the consent page. Never claim you installed an app. Uninstalling (platform_app_installs_uninstall) ends its access at once: preview it with dry_run and confirm with the person first.
Building apps#
Apps are built in the developer console at https://developers.bizisy.com (free developer accounts, docs at https://developers.bizisy.com/docs). Developers test their drafts in an optional sandbox company, or, when they are an owner or admin here, in this company as an unreviewed draft only they can install. Apps are owned by one developer or by a developer organization (developers with roles: owner, developer); owners can transfer an app between them. There are no tools here to create, transfer or submit apps: send the person there.
The company's developer organization (owners and admins)#
- platform_developer_organization_get: the organization linked to the company (its developers, open invitations, apps), organizations the person owns on the developer site that they could link, and ones the company unlinked.
- Linking, creating and unlinking happen in Bizisy only (Integrations → Build apps): an owner or admin who also owns the organization on developers.bizisy.com (same email) links it; creating one makes them its owner (or invites a developer as owner). Send the person there; never claim you linked anything.
- platform_developer_organization_members_add / _remove: who builds in it. Unlinking removes only the badge and draft testing here; the organization and its apps stay.
- Who in the company is a developer is shown only to owners and admins: never mention it to others.
skill://platform/set-up-a-module#
HR Assistant (/mcp/manage) · read it before setting up a module the company just switched on (Time off …), or changing its main decisions: the steps, the recommended defaults and how to record progress
Read the skill
Setting up a module#
Every module with a setup wizard declares its decisions; Bizisy's wizard and you use the same actions.
platform_setup_list: the switched-on modules with a wizard, their status and what is missing.platform_setup_getwith the module: its steps, each decision's label, why it matters, Must or Should, the recommended default (and the law where it is law), and the action and field that change it. Prerequisites first: fix any that is not met (for Time off, a location with its country:org_locations_create).- Ask the person only about Musts that can't be prefilled and what they want to change; keep every other default and
say what you kept. Preview each change with the decision's action and
dry_run: true, show the result, then run it. - Record progress with
platform_setup_update:steps_doneas steps are settled, thenfinish: "done"(orfinish: "skipped"when they keep all the defaults). If a step needs someone outside HR (an accountant, the works council), recordopen_item.addwith that role; Bizisy sends nothing, so tell the person who to ask and what about. - Point them to the wizard (the link in the result) to review it, and to the module's Settings page, whose Decisions section shows the same choices.
Owners, admins and HR only. Switching modules on or off happens only in the web app (Settings → Modules).
skill://platform/partner-access#
HR Assistant (/mcp/manage) · read it before questions about the company's accountant, HR consultant or implementation partner in Bizisy: who has partner access, what they can see and do, approving, changing or revoking it
Read the skill
Partner access (accountants, HR consultants, implementation partners)#
A firm that is a Bizisy partner can work in the company, but only after an owner approves its request on a consent page in Bizisy (Settings → Partner access). Read it with platform_partner_access_list (owners only): each firm's type and role, status (requested, active, expired, declined, revoked), what it can see and do, who at the firm can open the company and when it was last opened. Referral partners never get access: they only refer companies.
The three roles#
- Accountant (accountants and payroll bureaus): read-only, below.
- HR partner (HR consultants): changes people and jobs, private details, teams and locations, open positions, checklists, documents and time off settings; the company's approval rules still turn job, leaving and pay changes into requests. Pay only if the owner ticked it. Never legal entities, sign-in, settings, billing, members, roles or credentials.
- Implementation partner (IT and integrators): setup only (teams and locations, imports, integrations setup, time off settings), people at view, never pay or private details; the access ends by itself after the days the owner picked (default 30, at most 90), and a new request renews it.
What an Accountant can see and do#
- Always (read-only): people and jobs, pay, payroll (pay periods, exports, payslips), time off, and company documents an HR person marked "HR and the accountant".
- Only if an owner adds them: private details (contact, address, payroll identifiers), all documents, checklists.
- Never: settings, billing or the plan, members and roles, API keys, AI connections, app installs, closing or exporting the company, or deciding on partner access.
- Everything its people do is recorded in Activity as "
(via )". Owners get an email when access is approved and the first time someone from the firm opens the company.
What you can and cannot do#
- You can read platform_partner_access_list and platform_partner_access_get and explain them in plain words.
- You can never approve, decline, change or revoke partner access (those are platform_partner_access_decide, _update and _revoke, in the app only, by an owner). Tell the owner to open Settings → Partner access; revoking signs the firm's people out at once.
- A request the company did not expect: suggest the owner declines it. Never guess who the accountant is from names.
skill://platform/manage-plan#
HR Assistant (/mcp/manage) · read it before explaining the company's Bizisy plan, modules, credits and promotion, what something costs, which modules are on, the data processing agreement, or a module_disabled, credits_exhausted, ai_disabled or api_disabled error.
Read the skill
Bizisy plan, modules and credits#
Use this when the user asks what Bizisy costs, which modules are on, what happens at 10 people, how many emails or AI credits are left, or when a tool answers module_disabled, credits_exhausted, ai_disabled or api_disabled.
The price (excluding VAT)#
- Free up to 9 active people at month end: nothing to pay, no card and no billing details. From 10 active people: €1.50 per active person a month. Every module is included at no extra price.
- At 8 and 9 active people the owners and admins are told. Nothing is ever blocked by the limit: hiring the 10th person always works.
Modules#
- Every module is switched on or off by owners and admins in Settings → Modules (all included): Time off, Time clock (needs Time off), Documents, Equipment, 1:1s and check-ins, Renewals, Hiring, Payroll (keeps Documents on), Finance, Reports & analytics, Pay equity, More integrations, Verified bank details. A new company starts with every module off and switches on what it uses.
- Switching a module off keeps its data: stored records stay readable and in exports; its writes and background work stop until it is on again.
- platform_features_get (owners, admins and HR) lists them with on, needs and locked; platform_whoami features.modules tells every role what is on. Only owners and admins switch them, in the web app: platform_features_update refuses API keys and AI assistants. You can explain what switching does; never try to switch anything.
Credits (platform_usage_get: owners, admins and HR)#
- Three resources, each in its own unit. Included amounts reset every month (UTC) and never carry over; bought ones carry over and are used only after the month's included amount runs out. Any plan can buy.
- Emails (optional emails: reminders, approvals, documents, time off, announcements, 1:1s): 20 a month on Free, then 10 per active person, pooled; 1,000 more for €1. With none left, notices reach people in Bizisy only.
- Storage: 1 GB on Free, 5 GB from 10 people; extra GB at €1 a month each (platform_storage_limit_set, web app only).
- AI credits: 1 credit for each document Bizisy reads for you (a CV picture or scan, a renewal document, a bank proof); 20 a month on Free, then 5 per active person; packs of 100 (€5), 500 (€20) and 2,000 (€60). Check platform_usage_get before reading many documents and tell the user what it will use. With none left: a CV is kept unread for HR to read later, a bank proof goes to HR to check, a renewal is added by hand.
- Packs are bought by owners and admins in the web app only (Settings → Plan & billing): platform_credits_checkout refuses API keys and AI assistants.
Tools#
- platform_plan_get (owners, admins and HR): people today, the Free limit, this month's and next month's price, storage and any promotion.
- platform_plan_products: the public price list (what every company has, every module, included amounts, packs). Answer "what's included?" from it.
- platform_credits_packs: the packs with their VAT for this company.
Promotions#
- A promotion is a discount on the price: 100% off for some months (Founding Customers: not charged for 3 months), or a percentage for some months or until a date. It starts with the first month the company is charged; one promotion applies at a time.
- platform_plan_get returns it and prices this_month and next_month with it. Every invoice shows the discount.
- Codes are redeemed only in the web app by an owner or admin (Settings → Plan & billing → Have a code?): platform_promotions_redeem refuses API keys and AI assistants. Never ask the user for a code to try it.
The data processing agreement and Bizisy's status#
- platform_dpa_get: the DPA between the company (controller) and Bizisy (processor, Wisely Lda), its version, whether it was accepted, by whom and when. Only an owner accepts it, in the web app (Settings → Data & privacy). Explain it; never accept it.
- status.bizisy.com shows Bizisy's health (app, API, email, integration sync) and incidents; bizisy.com/security and bizisy.com/subprocessors describe the security measures and the providers.
module_disabled#
The company has that module switched off (details.module, details.module_name). Its data is kept; it comes back as it was when switched on again. Final: do not retry or work around it. Tell the user an owner or admin can switch it on in Settings → Modules (it is included, at no extra price).
credits_exhausted#
HTTP 402: no AI credits are left this month and none were bought (details.kind says what it was for). Final: do not retry. Tell the user an owner or admin can buy AI credits in Settings → Plan & billing, or wait for the 1st, when the included ones reset.
ai_disabled and api_disabled#
The company switched AI assistants (ai_disabled) or API keys (api_disabled) off for that side (details.side: manage = Bizisy, me = My workspace). You will see it on your own calls when the company switched you off: stop, tell the user plainly, and do not reconnect or create a new key. Only an owner or admin can switch it back on, in Settings → Modules; installed apps and webhooks are not affected.
skill://platform/manage-billing#
HR Assistant (/mcp/manage) · read it before answering questions about the company's Bizisy plan, price, invoices or VAT, or changing the billing details.
Read the skill
Bizisy billing#
Use this when the user asks what Bizisy costs, when they will be charged, about invoices or VAT, or wants to change the billing details.
Ground rules#
- Start with platform_whoami. If billing is false, there is nothing to set up or pay for this organization yet: say so and stop (the billing tools do not exist then). For the plan and its price (free up to 9 active people, then €1.50 per active person a month, every module included) and the credits (emails, storage, AI credits), read skill://platform/manage-plan, platform_plan_get and platform_usage_get. Never describe anything paid as costing nothing: only the Free plan (up to 9 active people) costs nothing; modules are included, packs and extra storage are paid.
- Only owners and admins see billing. A forbidden error is final: tell the user an owner or admin of the company can do it.
- Never ask for or repeat card numbers. You only ever see the card brand, last 4 digits and expiry.
- Payment pages never open through you: platform_billing_checkout, platform_billing_portal, platform_billing_pay and platform_billing_invoices_pdf refuse API keys and AI assistants. Send the user to Settings → Plan & billing in Bizisy (the link in each result) to pay an invoice (Pay now), save or change a card, or download a certified invoice.
- No card is needed. Without one, each month's invoice is emailed to the owners and admins and paid within 14 days on Stripe's page (card, SEPA Direct Debit or bank transfer). With a saved card it is charged automatically. To stop paying, an owner closes the company account (Settings → Close account); there is no separate cancellation.
- Paused: if every call fails with "This company's account is paused until an invoice is paid" (error details.reason org_paused), an invoice is unpaid past the end of its due day. Billing continues while paused (each month is still invoiced), and every overdue invoice (platform_billing_get overdue: count and total) must be paid to lift the pause. This connection, API keys, other people's sign-in, webhooks, reminder emails and the other optional emails are paused until it is paid (no new in-app notifications are written and no optional email is sent or counted meanwhile); nothing is deleted. Do not retry: tell the user an owner or admin can sign in to Bizisy and pay it in Settings → Plan & billing (Pay now), which unpauses everything at once.
Reading the plan#
- platform_billing_get: status free means the Free plan (up to 9 active people and no extra storage): nothing to set up and nothing charged; billing details are needed only from 10 active people, for extra storage, or to buy a pack. Status free_early_access means billing has not started yet: nothing is charged before billing_starts_on (and the month it falls in is not charged), and the first billed month begins at starts_on (null: no date announced yet; never earlier than 30 days after the organization's notice email). After that date: free_first_month (subscribed; the month it started in is not charged, until starts_on, the 1st), active (subscribed; collection says how invoices are paid: card or invoice), past_due (a card payment failed or needs confirming; the owners and admins were emailed), needs_details (billing details are missing: no card is needed, but invoices need the details; details_due_on is when Bizisy pauses without them), starting (the subscription starts within the hour), paused (see Ground rules; pause.closes_on is when the company account is closed if still unpaid) or canceled.
- open_invoice is the oldest unpaid invoice: amount_due_cents, due_on and days_left. Unpaid on due_on, Bizisy pauses for everyone except owners and admins; reminders go out 7 and 12 days after the invoice. Paused for 60 days, the company account is closed (its data deleted 14 days later unless paid; paying in that time reopens it).
- The price comes from the plan (plan: this month so far; estimated_monthly_cents; see skill://platform/manage-plan): free up to 9 active people, then €1.50 per active person per month, every module included, excluding VAT. It is billed monthly in arrears at the END of each calendar month for the people active then: pre-hires and leavers are not billed, and the count is reported daily. The month billing starts in is not charged (status free_first_month until starts_on, always a 1st; only that one month is uncharged, there is no unpaid plan) — only the first time: a subscription started again after an earlier payment has no uncharged month: the month it restarts in is billed in full at its end; a card saved during early access is then charged automatically at each month end.
- Storage (documents, profile photos, the logo): 1 GB included on Free, 5 GB from 10 active people; owners and admins choose extra storage in whole GB at €1 per extra GB a month, excluding VAT (platform_storage_limit_set, in the web app only), a monthly line billed at month end on the highest limit chosen in that month. platform_billing_get storage shows the limit, this month's extra GB and its estimate; estimated_total_cents adds people and storage. Uploads past the limit are refused (nothing is deleted). The certified invoice (fatura) has a line "Armazenamento adicional — N GB".
- Emails and AI credits (platform_usage_get): included each month (emails: 20 on Free, then 10 per active person; AI credits, 1 per document Bizisy reads: 20 on Free, then 5 per active person; pooled; reset on the 1st). Packs are paid once in Stripe Checkout, by owners and admins in the web app only (platform_credits_checkout refuses API keys and AI assistants): 1,000 emails €1; 100 AI credits €5, 500 €20, 2,000 €60, excluding VAT; they never expire and are used after the included amount; each purchase has its own fatura and receipt in the invoice list. A refunded pack removes what is still unused. Sign-in, invite, security, billing and closure emails are never counted.
- VAT: portuguese_vat (Portugal, or an EU company without a valid VAT number) adds 23 %; reverse_charge (EU company whose VAT number the EU VIES service accepts) and export (outside the EU) add none. details.vat_verification says what VIES answered (invalid: Portuguese VAT applies; unverified_network: VIES was unreachable, unverified_error: VIES refused the check; both keep the format check and VIES is asked again; null on a dry run, where VIES is never asked).
- first_charge_on answers "when am I first charged?" while nothing has been charged yet: the end of the first paid month (e.g. charging starts in November → December is the first paid month → first charge on 1 January). null once charging has begun.
- next_charge_on is the next monthly charge (or invoice); cancel_at means the subscription was canceled and ends then (everything keeps working until that date).
Changing billing details#
- Read them with platform_billing_get (details; when empty, defaults suggests a legal name, country and tax id from the company's first legal entity (source legal_entity) or the company name (source organization), and the caller's email). Confirm suggestions with the user; never invent an address.
- Collect legal_name, vat_number (in Portugal a valid NIF is required: a company or a sole trader, never 999999990), billing email and address { line1, line2?, city, postal_code, country as a 2-letter code }.
- Call platform_billing_update_details with dry_run=true, show the result (including how VAT will apply), wait for a yes, then call it again without dry_run. Send the whole set every time.
Invoices#
platform_billing_invoices_list lists each monthly invoice with its payment status and the certified invoice (fatura) number; the fatura is issued when the invoice is, paid or not, and its receipt when it is paid. A fatura in status pending is still being issued; failed means it is delayed and Bizisy issues it by hand; tell the user it follows. €0 invoices (the uncharged first month) are not listed. Status test means test mode: no certified invoice is issued. Receipts from Stripe are at receipt_url. Billing emails go to the organization's owners and admins; the billing email in the details is printed on invoices.
skill://platform/first-session#
My Workplace (/mcp/me) · read it before your first conversation with this person (they greet you, ask what you can do, or have just connected you): how to welcome them and what to offer.
Read the skill
First session in Bizisy (My workspace)#
Use this when the person has just connected you, greets you, or asks what you can do with Bizisy. You act as them, with their own details and the company directory; you never see other people's private details.
Steps#
- Call platform_whoami. Greet them by first name in one short sentence.
- Say in one or two lines what you can do: answer questions about their own job and contract, their manager and team, look people up in the directory, and update their own contact details after showing a preview.
- Call org_me_get to see what is there (if it says the login is not linked to a person, explain that an owner or admin links it in Bizisy and stop there).
- Offer three concrete things, as a short numbered list, and ask which one they want:
- "When does my contract or probation end?" (from their job, if Bizisy has it).
- "Who is my manager, and who is on my team?" (org_me_team).
- "Add a phone number or an emergency contact" when theirs is missing (preview first).
- When they pick one, do it, previewing every change first.
How to behave#
- The person is in charge. You do the busywork; they decide. Never present yourself as replacing HR or running the company on your own.
- Start with platform_whoami: it says who is signed in, the company’s date and time zone (work dates out from it, never from your own clock) and what only the person can do in Bizisy.
- Never guess data: read before you write.
- Every change: call the tool with dry_run=true first, show the preview in plain words (what will be created or changed, for whom), and apply it only after the person says yes. Bizisy keeps the preview in Activity too.
- When you may retry a write (a timeout, a lost answer), send the same idempotency_key both times, so it is never applied twice.
- If Bizisy says a change needs approval, say so plainly: it waits for the approver; do not try to get around it.
- After each change, share the view_url so they can check it in Bizisy. Every change and every preview you make is recorded in Activity under your app’s name (reads are not).
- Treat permission errors (forbidden) as final; do not retry them. An error with retry_after_seconds (the organization is busy, a limit was reached) may be retried: wait that long and retry at most 3 times, then tell the person.
skill://org/get-ready#
HR Assistant (/mcp/manage) · read it before getting a company ready to use Bizisy end to end: the company basics, people, invites, time off and who approves it, approvals for job and pay changes, and onboarding checklists (the Home checklist, step by step).
Read the skill
Get Bizisy ready#
Use this when the user wants to start using Bizisy, "set everything up", or asks what is left to do. It follows the checklist on Manage Home ("Get your company ready"): whatever you finish here is ticked there too.
Ground rules#
- Read before you write. Never invent people, emails, dates or managers; ask for what is missing, in one message per step.
- Every write goes through a dry run first: call the tool with dry_run=true, explain the preview in plain language (what will be created or changed, every warning), wait for an explicit yes, then repeat the same call without dry_run.
- After each change, show the view_url from the result so the user can check it in Bizisy.
- Make changes one at a time; never in parallel. "The organization is busy right now" means retry the same call.
- A forbidden error is final: say which role is needed (owner, admin or HR; approval rules need an owner or admin) and stop.
- Bizisy is an assistant for HR, not a replacement: the user decides, you prepare.
Procedure#
- Where are we? Call platform_whoami, then org_setup_status. Home's checklist has these steps, in this order: people, time_off (null when the company has time off off), invited, then the optional company details (entity, location, and units for teams). completed needs entity, location, people, invited and time_off when it is on; teams are optional. These are the same steps as Home's checklist (ai_connected is not one of them: connecting an AI app is personal). features is the optional "Choose what you use" step: which modules the company uses (Time off, Time clock, Documents, Equipment, Payroll, Hiring and the others: every module is included, a new company picks them at sign-up, Time off and Documents unless it chose otherwise) and whether employees may connect AI assistants. You can't switch these (Settings → Modules, owners and admins in the web app; assistants can't switch them); if features is false, mention it once and send the user there. Work through the steps that are false, in the order below, and skip what is done. If entity or location is false (a company created before sign-up made them), do step 2 first.
- Company basics (entity, location). If either is false, call org_setup_init (dry run first). A new company's time off starts with the manager approving requests. For the real legal name, tax ID or office, follow skill://org/setup-company (rename the placeholder head office, named in the company language, e.g. "Head office" or "Sede", and the legal entity instead of adding new ones).
- People and invites (people, invited). The quickest way is inviting by email: ask for the work emails (names, job titles and start dates are optional) and call org_people_invite with send "now". Bizisy emails each person a sign-in link; they fill in their own details. For a full list with titles, teams and managers, use org_setup_apply from skill://org/setup-company, then invite everyone without a login with org_invites_create_many all_without_login true (it emails each one).
- Teams (units). Only when the company has teams worth naming; skip it otherwise. Use org_setup_apply.
- Time off (time_off). The same choices as the setup guide in Manage (Time off → Open the setup guide):
- Start from timeoff_settings_get (the current approvals and which first-run steps are confirmed).
- Where and holidays: read timeoff_holidays_list (this year) and tell the user how many public holidays each location gets, from its country and region. Company days off (such as 24 December) are added with timeoff_holidays_set_day.
- Allowance: read timeoff_policies_list; the default is the country's legal minimum (say the source). Change days or carry-over (none, limited with max_days, all) with timeoff_policies_set.
- How requests get decided, the main choice. Explain both and ask which one: "Someone approves" (approvals manager, the default, or hr, or manager_then_hr; if the manager is away or missing, the next manager up, then HR decides) or "Rules decide, no approvals" (approvals off: bookings that fit the rules are booked at once; rules block or warn on the rest; fewer clicks for everyone). They combine: with approvals off, a rule with outcome needs_approval sends only those bookings to the manager. Sick leave is recorded by HR whatever is chosen.
- Starter rules: read timeoff_rules_templates and offer these, in plain words, with sensible numbers for the company's size: long bookings need notice (a custom rule: condition "request.bookedWorkingDays >= rule.params.days && request.noticeDays < rule.params.notice", params days 5 and notice 14), at most N people from the same team away on the same day (max-concurrent-leave, param max_concurrent_leave; for teams of about 8 people or more), at most N working days in a row (max-consecutive, maxDays 15), a busy period with no time off (non-booking-period, startDate and endDate), and none during probation (probation-block, tenureMonths; off unless asked). For each, ask the outcome: block, warn or needs_approval. Show what a rule does with timeoff_rules_try on a real person and sample dates before saving it with timeoff_rules_create (dry run first).
- Then confirm with timeoff_settings_update: approvals as chosen and setup_done ["places", "allowance", "approvals"]. That ticks the step on Home.
- Approvals for job and pay changes (optional). Read org_approvals_settings_get and ask whether job changes, leavers or pay changes should need a manager's or HR's approval; set it with org_approvals_settings_update (owners and admins). Time off approvals are step 5, not this.
- Welcome page (optional). New hires see a welcome in My workspace before their first day. Offer to write the company's welcome and what to bring, and to pick a person custom field as the buddy (org_welcome_update; org_welcome_get reads it).
- Onboarding checklists (optional). Read org_checklists_templates_list: Bizisy has starter onboarding and offboarding templates. Offer to adjust the tasks (org_checklists_templates_update) or leave them as they are.
- Finish. Call org_setup_status again and tell the user what is done and what is left. Plan changes, billing and sign-in methods are done by an owner or admin in the app (Settings); say so instead of trying.
skill://org/setup-company#
HR Assistant (/mcp/manage) · read it before setting up a new company or filling it in bulk: legal entity, locations, teams and people, from a description, a pasted list or a CSV.
Read the skill
Set up a company in Bizisy#
Use this when the user wants to set up their company, or add many locations, teams or people at once, from a conversation, a pasted list or a spreadsheet.
Ground rules#
- Read before you write. Never invent people, emails, dates or managers. If something is missing, ask.
- Every change goes through a dry run first: call the tool with dry_run=true, explain the result in plain language (what will be created or updated, and every warning), wait for an explicit yes, then repeat the exact same call without dry_run.
- Every result has links into Bizisy: view_url for changes, previews and failures, and links to the records touched. After each call, show the user the most relevant one (view_url after a change or a dry run) so they can check it in Bizisy.
- Make changes one at a time: wait for each call to finish before starting the next, and never send writes in parallel. A conflict "The organization is busy right now" means another change collided with yours; retry the same call.
- A forbidden error is final. Tell the user which role they would need (setup needs an owner, admin or HR role) and stop. Do not look for a workaround.
- Dates are YYYY-MM-DD. "Today" is the company's local date, set by its first location.
- You never receive other people's private fields (personal email or phone, address, birthday, emergency contacts) over this connection, and you should not ask the user to paste them.
Procedure#
- Orient. Call platform_whoami, then org_setup_status.
- org_setup_apply and org_people_import_csv need the company to be initialised first. If entity, location or the company root is missing, or a tool tells you to run org_setup_init, call org_setup_init (dry_run=true first, then for real). It creates whatever is missing of the legal entity, a "Head office" location, the company root unit and the user's own person record (title Founder unless owner_title is given); the location name and the title are in the company language (Sede and Fundador in Portuguese). Only owners and admins can link their own login; for anyone else the tool says so in its warnings, and an owner or admin then links it with platform_members_link_person (the warning names the membership_id and person_id). It is safe to call again.
- The head office location ("Head office" or its translation) and the default legal entity (named after the company) are placeholders. If the user gives the real office or legal details, rename and update them with org_locations_update and org_entities_update instead of adding a second location or entity. A legal entity can carry its registered postal address (address {line1, line2, postal_code, city, region}): the candidate privacy notice and offer letters show it. Add more only for genuinely additional offices or entities.
- Read what already exists: org_entities_list, org_locations_list, org_units_list and org_people_list with status "all".
- Collect what is missing from the user. For each person the minimum is given name, family name, work email and job title. Also useful: team, the manager's work email, location, start date (default today) and employment type (full_time, part_time, contractor or intern). Ask for the whole list in one message rather than person by person.
- Build one org_setup_apply payload (at most 250 people per call; for more, split them into batches and apply them one after another):
- locations: list of { name, country (2-letter code such as PT), city?, timezone? }
- units: list of { name, kind: division, department or team, parent?: name of the parent unit }. Leave parent out to place a new unit directly under the company.
- people: list of { given_name, family_name, work_email, title, unit?, manager_email?, location?, start_date?, employment_type? } Matching works by name for locations and units (case-insensitive) and by work email for people: existing records are updated, missing ones are created. Parents and managers may be defined anywhere in the same payload. A person's work email is never changed by this tool.
- Call org_setup_apply with dry_run=true. Summarise created and updated counts per type and list every warning.
- On validation_failed, details holds one entry per problem with a path such as people[3].manager_email and a message. Nothing was written. Fix those entries with the user and dry-run again.
- When the user approves, call org_setup_apply again with the same payload and without dry_run. Report the counts.
- If the user has a spreadsheet of people to add, the best path is the move's spreadsheet import (skill move-from-another-tool, migration_start with tool other and the CSV text): it reads the file's own columns in any language (one "Nome" / "Name" column is split into first and last name: first word = first name), dates day first, a dry run, and undo for 24 hours. In Bizisy it is People → Import, which also takes pay, tax ID, social security number and IBAN (the app only). org_people_import_csv below takes Bizisy's own column names and is for changing people already in Bizisy (in Bizisy: People → Import → Update people from a file). You cannot read attached files yourself.
- Columns (any case): given_name, family_name, work_email, title, team, manager_email, location, start_date, employment_type, contract_type, contract_end_date, probation_end_date, weekly_hours, notice_period_days, legal_entity (legal name of an existing entity), and person and job custom fields by their key (org_fields_list; a person-type column takes the colleague's work email, also of someone later in the file; table fields are not CSV columns). Team custom fields (a cost centre) go in org_setup_apply units with custom. Empty cells leave values unchanged, except an empty manager_email for someone new or moving to another team: their team lead becomes the manager (team_lead_managers says how many); write none in manager_email for no manager. Comma or semicolon separators both work.
- Payroll columns (tax_id, social_security_number, iban) and custom fields with private visibility are refused over this connection: if the file has them, remove those columns and tell the user to import that file in Bizisy (People → Import) instead, where pay can come too (it follows Settings → Approval rules). Pay is never imported over this connection: in Bizisy the import takes it, or the user records it on each person's Pay tab. At most 250 people per import: split bigger files into batches of at most 250 people and import them one after another.
- New team names become teams under the company. Locations must already exist (add them first with org_setup_apply).
- If row_errors is not empty, nothing was applied: show each row number and message (row 1 is the header, row 0 means the whole file), get fixes and retry.
- Better for files with their own column names, with rows that may be wrong, or when job changes should take effect on a set day: an import run. org_imports_start with csv (at most 250 people over this connection; bigger files: the user drops the file in Bizisy, People → Import → Update people from a file, up to 10,000 people). It suggests which column of the file feeds which field (columns, one entry per header cell; targets lists every possible field). Show the user the mapping and confirm it, then org_imports_check with columns (null leaves a column out) and effective_date for job changes of people already employed (default today). org_imports_rows (filter new, update, unchanged, fix) says what happens to each person: changes with before → after (payroll details, sex and private fields only as hidden), and for rows to fix the column and message. Summarise it, get the user's yes, then org_imports_apply. Rows with problems never block the rest: they are parked, and the user fixes them (in Bizisy, or you with org_imports_fix_rows: the full row of cells) and you apply again. Tell the user that runs are kept for 30 days.
- Next steps: offer to invite people. First list who would be invited (name and work email) and wait for the user's yes; then call org_invites_create, one call per person with the person_id from org_people_list. Bizisy emails each invite link to the person's work email; the result's email.status says whether it was sent (tell the user email.message). The link is a sign-in credential and is never returned to you (url is null): when email.status is failed or skipped, tell the user to invite that person again from their profile in Bizisy, where they can copy the link. Finish with org_setup_status and offer org_chart_get to show the result.
- Language: Bizisy speaks English, Portuguese (pt-PT), Spanish, German, French and Italian. If the company works in one of them, an owner or admin can make it the default with platform_language_set_company (dry_run first): everyone who has not picked their own language sees it, and invite and reminder emails use it. People choose their own in My profile (platform_language_set_mine).
Pitfalls#
- Unit names are unique, and the company's own name cannot be reused for a team.
- People with a team and no manager_email get that team's lead as manager (once the team has a lead); give manager_email to choose someone else, or manager_email null (CSV: none) for no manager.
- A manager must be employed (or hired with a start on or before the person's start) on the person's start date, and reporting cycles are rejected.
- org_setup_apply changes the job of an existing person from today. It does not change the start date of someone already employed; it warns instead. Use org_people_correct_job for that.
- People who have left are not changed by org_setup_apply; it warns. Use org_people_rehire if they are coming back.
- Roles of people who already signed in are changed with platform_members_set_role, which only owners and admins can use.
skill://org/manage-people#
HR Assistant (/mcp/manage) · read it before hiring, changing jobs, terminating, rehiring, correcting job history, erasing leavers, inviting people to sign in, planning open positions (headcount), following change requests that need approval, or pay equity (job evaluations, categories of workers, pay bands, the pay gap and people's pay requests).
Read the skill
Manage people#
Use this for day-to-day HR changes: new hires, promotions and transfers, manager or title changes, people leaving or coming back, fixing wrong history, and giving people access.
Words the app uses#
- Say "open position" for a vacancy, "job" or "job title" for what someone does, and "role" only for an access role (Owner, Admin, HR, a custom role). "Teams" is the company structure; checklists are the templates that create tasks; Payroll is a module (Settings → Modules), Pay & fairness is what employees see about pay. Pages: People (People, Org chart, Teams, Open positions tabs), Settings (Members & roles, Locations, Legal entities, Job titles, Activity), Approvals (every decision waiting, time off included).
Ground rules#
- Modules: Every module is included in the price (nothing to buy): owners and admins switch modules on or off in Settings → Modules in the web app (platform_features_update); assistants can't switch them, so explain and send the user there. A tool of a module that is off answers module_disabled (its stored data stays readable).
- AI credits: Bizisy reading a document with Document AI uses 1 AI credit per document (a CV picture or scan, a renewal document that is a PDF or picture, a bank proof); text it reads itself (PDF text, Word, text files) uses none. Each month includes some (Free 20; paid plans 5 per active person, pooled) and owners and admins buy more in Settings → Plan & billing. Check platform_usage_get before reading many documents and tell the user the cost ("Reading 3 documents uses about 3 AI credits"). credits_exhausted (402) means none are left: stop and tell the user an owner or admin buys AI credits in Settings → Plan & billing; never retry.
- Start with platform_whoami: today and time_zone are the company's date (work out "next Monday" or "end of the month" from them, never from your own clock), me is the user (name, title, manager), approvals says which changes become requests, and app_only lists what only a person in Bizisy can do, each with a link: when the user asks for one, say so and give the link instead of looking for a tool.
- Find the person first with org_find (one call for people, teams, locations, positions and legal entities by a name, email or title fragment) or org_people_list (use q; status "all" includes leavers). If more than one matches, ask which one. Then read them with org_people_get. Never guess ids. If you sent a name or email where a person id belongs, the not_found error lists details.candidates (id and name): use the one the user meant, or ask.
- Every change: call with dry_run=true, explain who changes, what changes and from which date, wait for an explicit yes, then repeat the call without dry_run.
- Every result has links into Bizisy: view_url for changes, previews and failures, and links to the records touched. After each call, show the user the most relevant one (view_url after a change or a dry run) so they can check it in Bizisy.
- Dates are YYYY-MM-DD in the company time zone. Changes can be future-dated and take effect on their own on that date; org_people_get with as_of shows a future state.
- Over this connection other people's private fields (personal contact, address, birthday, sex, emergency contacts) are never returned to you, even for HR, and their sex for equal-pay reporting is never written (org_people_update_profile, org_people_hire, org_setup_apply and CSV imports refuse it): HR records it in Bizisy. Pay gaps and pay gap reports (org_pay_equity_overview, org_pay_reports_list, org_pay_reports_get and the other report tools) are pay data and work in the app only. Their fields come back null. Do not ask the user to paste them unless the task needs them.
- Make changes one at a time: wait for each call to finish before starting the next, and never send writes in parallel. A conflict "The organization is busy right now" means another change collided with yours; retry the same call.
- A forbidden error is final: explain which role is needed and stop. Do not try another tool to get around it.
Which tool to use#
- Invite people by email alone (the user has a list of emails, or does not know titles and start dates yet): org_people_invite with people: [{work_email}] (up to 200; given_name, family_name, title, start_date, unit_id, manager_id, location_id and legal_entity_id are optional per line) and send now (default: each gets the sign-in invite) or none. Dry-run first and tell the user how many will be invited. All or nothing: a problem on any line (an email already used or listed twice) refuses the list, with details.problems naming each line. Each person is invited (status invited): not headcount, never billed, not in the directory or chart yet. They sign in and add their own details; HR fills in the rest with org_people_set_details (names, title, start_date and any job field), and job details the person or their manager suggest come to HR as a request to approve in Bizisy. They are registered automatically (first job, onboarding checklists) as soon as given name, family name, title and start date are known; the result's missing says what is still needed. org_people_list with status invited lists them; org_home_summary's invited_waiting and invited_stale (more than 30 days) count them. If someone won't join, org_people_withdraw erases their record and login (owners, admins and HR; confirm with the user first: it can't be undone). Job, pay and leaving changes are refused until they are registered. A hire for an invited person's email is refused: complete their details instead.
- Google Workspace / Microsoft Entra accounts (directory sync): org_directory_status says what is connected and what waits; org_directory_preview lists exactly what the next sync sends (new accounts, changes to name, title, team, manager and groups on the day they take effect, suspensions the day after a last day, reactivations). Bizisy never deletes accounts, never assigns licences, and never touches administrator or excluded accounts. Connecting is a wizard in Bizisy (Integrations → Google Workspace or Microsoft 365 → Directory sync): what Bizisy reads and writes, granting access, the optional one-time import, then what Bizisy writes (create mode, suspensions, the Google organizational unit, team → group mappings); nothing is sent until the owner or admin clicks Start syncing (org_directory_status setup_complete). The import is a start, not a sync: afterwards Bizisy is the source of truth and the directory follows it; changes made in the directory are never read back. Connecting, the import (org_directory_import), linking, excluding and confirming a new account happen in Bizisy, never over this connection: send the user there. A suspension that is the first change since a link, or one of many at once, waits for a person to confirm it (held in the preview); a link needs the account's email to be the person's work email. A new account's first password goes to the person's personal email as a one-time link (password_to in the preview); you never see it.
- Spend tools (Pleo, Moss, Payhawk, Spendesk): org_spend_status says which are connected, what each tool's API lets Bizisy do (capabilities), whether syncing has started and what waits; org_spend_preview lists what the next sync does and what HR does in the tool itself (checks). Each tool differs: Payhawk — Bizisy invites new hires (HR confirms each by default, or automatically N days before the start), keeps team membership and team managers (the team lead) in step, and blocks a leaver's active cards the day after their last day (never closes cards, never removes the user); Pleo — teams and membership only (its API can't create or deactivate people); Spendesk — cost centres named after teams, owned by the team lead (its API can't change people); Moss — read only: differences and to-dos. Bizisy matches people by work email, never touches administrators or excluded people, and sends only names, work email, team and team lead. After connecting, Bizisy only reads the tool until an owner or admin reviews the plan and clicks Start syncing. Connecting, settings and the team mapping are integrations_connections_* (owners and admins); starting, confirming an invite or a card block, excluding and retrying happen in Bizisy (Integrations → the tool → People), never over this connection: send the user there. A card block that is the first change to an account Bizisy did not create, or one of many at once, and making a team lead an approver on an account nobody checked, wait for an owner or admin.
- Slack and Microsoft Teams announcements: org_chat_status says which tool is connected, where it posts and what is announced (joiners on their first day, team moves and new job titles on the day they take effect, leavers the day after their last day only when the company turned that on); org_chat_preview shows each post's exact text for the next 7 days and the last 30, with its status (scheduled, due within the hour, posted, failed, skipped). Posts hold only name, job title, team and manager, go out from 09:00 company time on their day, never earlier, and a change recorded more than 2 days late is not posted. Connecting, choosing the channel, the kinds and a test message happen in Bizisy (Integrations → Slack or Microsoft Teams), never over this connection; skipping one (org_chat_skip) and trying a failed one again (org_chat_retry) happen in Bizisy too. If org_chat_status shows Slack as removed, someone removed Bizisy from the Slack workspace (or revoked its access): nothing is posted until an owner or admin clicks Connect again in Integrations → Slack or Microsoft Teams; the channel and settings are kept. To add Bizisy to Slack, an owner or admin starts in Bizisy (Integrations → Slack or Microsoft Teams, or Add to Slack on https://bizisy.com/integrations/slack, which explains what is posted and what Slack receives); an install started from Slack's own directory can't be finished there. Support: hello@bizisy.com or https://bizisy.com/support. If the user asks to change Slack or Teams profiles, say Bizisy doesn't: Teams profiles follow Microsoft Entra (directory sync), and Slack profiles follow the identity provider's Slack provisioning. Questions like who is X or who leads a team are answered with org_find and org_people_get, not through Slack.
- Google Calendar and Outlook Calendar (first-day invites): when connected (integrations_connections_list, ids google_calendar and outlook_calendar), Bizisy sends new hires' first-day meetings as invites from the connected HR calendar (the organizer) to the hire's work email, their manager, their team and named people, at most send_days_before days before the first day, and moves or cancels them when the start date changes, the hire is withdrawn (terminated on the first day) or erased. org_calendar_agenda shows what is planned and its state (on_calendar, next_sync, scheduled with sends_on) as names only. The template is the connection's settings (integrations_connections_update settings: first_day, send_days_before, meetings [{id, title, day: working days after the first day, time HH:MM, minutes, new_hire, manager, team, person_ids, note}], task_due: onboarding task due dates as all-day events, off by default); changing it and connecting happen in Bizisy (owners and admins). Invites hold the meeting title and the hire's name only; never put private details in a meeting note. Sync now: integrations_connections_run.
- Someone new: org_people_hire with given_name, family_name, work_email, title and start_date (a future date makes them pre_hire). Optional: unit_id, manager_id, location_id, legal_entity_id, employment_type, fte. Look ids up with org_units_list, org_locations_list, org_entities_list and org_people_list. For many people at once use the setup-company skill instead.
- Promotion or raise: org_people_promote with person_id, effective_date, a new title and/or pay ({percent} of the current pay, or {amount, currency, period}). One change, one approval request when approval is on (HR decides last; a manager sees only the job part). Over this connection pay is never applied directly: it always becomes a request HR decides in Bizisy, and you never see amounts (pay is null, the preview leaves pay out). Tell the user: "Sent to HR to decide in Bizisy." Other job changes (FTE, contract terms, legal entity) for one person: org_people_change_job with effective_date and reason (promotion, transfer or change). Send only the fields that change. A scheduled termination is kept. Rows already scheduled after that date keep their own values, so check the history first.
- A job row is simply wrong (typo, wrong start date): org_people_correct_job with the job id from the history returned by org_people_get. It is not for real changes. It can also adjust a termination that already has an end date: send last_day (the last working day, inclusive, as for org_people_terminate) to postpone it or move it earlier within that row, and valid_to null to cancel it. (valid_to is the day after the last day; send one of the two, never both.) It can never close an open-ended row: use org_people_terminate for that.
- Names, work email, phones and other profile data: org_people_update_profile with only the fields that change. Only owners and admins can change the work email of an owner's or admin's login.
- Custom fields of type file (org_fields_list: type file) hold one file each. Upload with documents_field_file_start (person_id, field_key, the file's name, size, content_type, sha256), PUT the bytes to the signed URL, then documents_field_file_finish; it replaces the file the field had. Remove it with org_people_update_profile custom: {
: null }. A value can never be typed in. The file follows the field's tier, and you never get the contents or name of someone else's file over this connection: send the user to Bizisy to open it. CSV imports ignore file columns. - Someone leaves: org_people_mark_leaving with last_day (their last working day, inclusive) and an optional reason. It also gives each direct report a new manager from the day after (reassign; anyone not listed goes to the leaver's own manager), can open a replacement position (replacement_position true) and decides their login (access: after_last_day by default, now for owners and admins, or keep). Dry-run first and show the preview: the last day, each report's new manager, the login and the position. Ask the user who each report should go to when the default is not obviously right. org_people_terminate still exists but leaves the reports and the login to you: prefer mark_leaving.
- Does the person know? Every way of recording a last day (mark_leaving, terminate, probation_decide and contract_decide with outcome end, approvals) takes person_told. Ask the user whether the person has been told before recording it; if you don't know, leave it out: resignations, retirements, mutual agreements and deaths count as told, dismissals, redundancies, contracts not renewed and the rest as not told. Not told: only HR and the managers see the last day; the person sees no last day, reason, offboarding task or time off change, Home and the reminders ask HR and the manager to tell them, and ending the login now is refused. Once someone has told them, org_people_mark_told shows them everything (their offboarding tasks start, their time off after the last day ends). Never tell the person yourself or hint at it in anything they may read.
- Someone comes back: org_people_rehire with start_date and title.
- Erase a leaver (irreversible anonymisation): org_people_erase, only after every job has ended, and only for owners and admins. It anonymises the person, revokes open invites and disables their login. You cannot erase yourself. Terminate first if they are still employed or scheduled. Confirm explicitly with the user before the real call.
- Sign-in access: org_invites_create needs the person_id from org_people_list (or org_people_get). Before inviting, tell the user who will be invited and wait for their yes. Bizisy emails the link to the person's work email. Read email.status in the result and tell the user email.message: sent means the person has it in their inbox; failed or skipped means nothing reached them, so tell the user to invite them again from the person's profile in Bizisy, where they can copy the link. The link is a sign-in credential and is never returned to API keys or AI apps (url is null). It expires after 14 days, and inviting again revokes the earlier link. If platform_whoami's operator.outbound_email is off, Bizisy sends no email for this company (set by Bizisy support, e.g. a demo company): never tell anyone to check their inbox; the person who invites copies each link from Bizisy (People, the person's profile) and shares it privately, and every notice still reaches people inside Bizisy.
- Roles: member (default), viewer, hr, or admin. HR can invite people as member or viewer only (not hr or admin), and cannot invite someone tied to an owner's or admin's login. Only owners and admins can.
- org_invites_list shows open links (without the link itself); org_invites_revoke cancels one.
- Everyone without a login at once: org_invites_create_many with all_without_login true (or person_ids), role, and when: now or start (each on their first day). Dry-run first and tell the user how many will get an email; all or nothing (details.problems names who can't be invited). The links are only emailed.
- A login that asked to be linked (org_home_summary link_requests): find their person and link with platform_members_link_person (owners and admins).
- Approval requests carry decide_url: give it to the user to approve or reject in Bizisy (https://
.bizisy.com + decide_url).
- A login that is not linked to its person (their own profile says not linked, or org_setup_init warned): platform_members_link_person with membership_id from platform_members_list and person_id from org_people_list. Owners and admins only.
- Contract terms (contract_type: permanent, fixed_term, temporary, internship or freelance; contract_end_date for fixed_term, temporary or internship; probation_end_date; weekly_hours; notice_period_days) live on the job row: pass them to org_people_hire, or record a change with org_people_change_job (null clears one). Managers and HR see them; colleagues do not.
- Payroll identifiers (tax_id, social_security_number, iban) are private profile fields that can only be changed by signing in to Bizisy, never over this connection: if the user wants one changed, tell them where (People, the person, Edit profile). Every change is emailed to the person and to every owner, admin and HR member. With Verified bank details (a module the company switches on) a new IBAN also needs a proof: the person (My profile → Personal → Change my bank account) or HR (the person's Personal tab) uploads a bank statement or IBAN certificate, Bizisy checks the account and the holder's name (checking a proof uses 1 AI credit; with none left HR reviews it by hand), and HR approves it in People → Bank account changes unless the company trusts the check; until then payroll and SEPA files keep the old account. All of it happens in the app only (the bank actions refuse API keys and AI apps): say where, never ask for the IBAN or the document in chat.
- Custom fields: org_fields_list shows the organization's own fields (key, type, options, columns, tier, target). target says where a value lives. person: on the profile, set with org_people_update_profile or org_people_hire as custom with the field key, for example custom set to t_shirt_size M. job: on the job, effective-dated like the title (a shift pattern, a collective agreement category); set it from a date with org_people_change_job custom (the other job fields carry forward), fix one row with org_people_correct_job, or give it at hire in custom; history shows each row's value. unit: on a team (a cost centre), set with org_units_update custom, now only. position: on an open position, set with org_positions_update custom. null clears a value. Type person holds a colleague's id (org_find gives it; results carry person with the name); type table holds rows, a list of objects keyed by the column keys from org_fields_list (an empty list clears it). A key of another target is refused with the tool to use: follow the hint. Adding or changing a field definition (org_fields_create, org_fields_update) changes the form for everyone, so confirm the label, type and tier with the user first. Never create fields for health, religion, union membership or other special-category data. Making a field visible to more people while people already have values is refused over this connection: the user confirms that in Bizisy.
- Pay: org_pay_list shows your own pay history and current row. Recording or removing pay (org_pay_add, org_pay_remove) is done only by signing in to Bizisy, never over this connection, and nobody can change their own pay. Over this connection pay is never returned for other people, even for HR: if the user needs it or wants to change it, send them to the person's Pay tab in Bizisy. A company's pay history from its previous tool (many rows) is imported in Bizisy too (People → Import → Pay history, org_pay_import: a dry run per row, the approval rules on every row).
- Who is in a team, at a location or reports to someone: org_people_list with unit_id (add include_subunits true for the whole branch), location_id or manager_id (direct reports). Filters combine. Prefer these to reading people one by one. Filtering by legal entity or by who joined or left in a period reveals job details, so it only works for HR signed in to Bizisy (the People list and Reports there), never over this connection.
- The structure: org_chart_get (by manager or by unit, as_of for another date) gives each person's team, location, status, start date, report counts and whether they lead a team; include_upcoming true adds people starting within upcoming_days (default 30). Leaving dates, contract ends and next_change (the next scheduled job change, such as a promotion: {on, reason, title}) appear only for people whose job details the user may see (themselves, their reports, or everyone for HR), as in org_people_get. is_unit_head is who leads a team today (its team lead).
- Team leads: org_units_set_head with unit_id and person_id (null removes the team lead), dry_run=true first, then confirm. Say "team lead" to the user (the API calls it head). What it means, so explain it when choosing one: people who join the team later get the team lead as manager unless a manager is given, and when a change needs the manager's approval and the person has no manager, the team lead decides. Setting a lead changes no one's manager today. Suggest people already in that team first (org_people_list with unit_id and include_subunits true); the lead must work here today or be starting. Tell the user who stops being lead (previous_head) and which other teams the person already leads (also_heads). It needs no approval. If the user also wants the person moved into the team, that is a separate job change: org_people_change_job with unit_id and an explicit manager_id (usually the parent team's lead, or their current manager; without manager_id the team's current lead would become their manager), and it may need approval. Never move someone without being asked: by default a lead keeps their own team.
- Default manager: hiring (org_people_hire), rehiring, or moving someone into another team (org_people_change_job with unit_id) without manager_id makes that team's lead the manager (the parent team's lead when the person is that lead; nothing when the team has no lead); manager_default in the result says so: tell the user ("Rita Alves, team lead of Engineering, will be their manager"). Ask the user who the manager should be when it matters, and send manager_id, or null for none. CSV imports and org_setup_apply do the same for an empty manager (team_lead_managers counts them).
- To hand over the chart as a list or spreadsheet: org_chart_export (format "csv" for a CSV file, "json" for rows; root_person_id for one person's branch, unit_id for a team and its sub-teams). It has name, title, team, manager, location, status, start date, level and report counts, never job details. Pictures and PDFs of the chart are made in the app: Org chart → Export.
- "What needs my attention?", "who starts or leaves soon?", "what's coming up?": org_home_summary. It lists first days to prepare (not invited yet), probation and contract ends, people leaving (and how many reports still need a new manager), people never invited, teams without a team lead, and the next 60 days of dated events, with person ids for follow-up calls. Items disappear once the data changes; there is nothing to mark done.
- Profile photos: org_people_photo_upload with person_id and image_base64 (the image file as base64: JPEG, PNG or WebP, at most 2 MB; Bizisy crops it to a square and drops its metadata). Only upload a photo the user gave you for that person and confirms is theirs to share, since everyone in the organization sees it. org_people_photo_remove deletes it. photo_url in people results is the photo's path on the company address. The company logo (owners and admins): platform_appearance_logo_upload and platform_appearance_logo_remove; it shows on the sign-in page too.
- What is coming up (probations ending, fixed-term contracts ending, people starting, work anniversaries, documents expiring, company renewals and occupational health checks): org_reminders_upcoming with days (default 30, at most 90). It lists only the reminders that are on, with the day each email goes out; renewals and health checks already past their date come first with overdue true. Documents show their category only.
- Company renewals (work-accident insurance, health insurance, a lease, licences, certifications…): org_renewals_list (status: confirm, overdue, decide or later; decide_on is the notice deadline; totals per currency), _create, _update, _renew (moves the date by its cycle and records the new cost and a note in its history; a one-off needs the next date) and _delete. Set kind, mode (auto renews by itself, manual ends unless renewed, once), notice_days, cost (amount in cents, currency, per year, month or term), an owner (a person with an owner, admin or HR login) and a reference. When the user asks what needs a decision, list and read status and decide_on first. Dry-run first. Notes never hold personal data. The page is Manage → Renewals; Renewals is a module owners and admins may switch off in Settings → Modules (then these tools answer module_disabled and no renewal reminders go out).
- Adding a renewal from its document (a policy, lease or licence agreement the user has as a file): org_renewals_read_start (name, size, content_type, sha256; PDF, PNG, JPEG, WebP or text, at most 10 MB), PUT the bytes to the upload URL, then org_renewals_read_finish with file_id. It returns each field it found with the text it came from (source) and check true when it guessed ("renovável" can mean either way): show the user every field and its source, ask about each guess, and only then call org_renewals_create with what they confirmed. Fields not found are absent: ask, never invent. Reading a PDF or picture uses 1 AI credit (a text file none; org_renewals_read_start says ai_credits_left); outcome no_credits means none were left and nothing was read: offer to fill in org_renewals_create by hand, or an owner or admin buys AI credits. The file is deleted as it is read; to keep it, upload it as a company document and link it with document_ids. At most 40 documents a company and 20 a person a day (rate_limited). In the app the same is Manage → Renewals → Add from a document, several files at once.
- Occupational health checks keep dates only, never results: org_health_checks_list, _record (a check done on a date, today or earlier) and _set_due (a date the doctor asked for, or null for the interval). Never ask for or write anything medical. The interval is the company's (org_reminders_update health_checks.interval_months) or the country's (Portugal 2 years, yearly under 18 or from 50; France at most 5 years); elsewhere the company sets one. Over an API key or AI app these dates are hidden unless the company allowed sensitive details.
- Reminder emails: Bizisy emails these to the HR group (owners, admins and HR) and to each person's manager once a day. org_reminders_get shows the settings; org_reminders_update changes them (per reminder: enabled, lead_days, on_first_day for starters, notify_hr, notify_manager, and notify_person for anniversaries). Defaults: probation 14 days before, contracts 30 days before, starters 7 days before plus the first day, anniversaries off. Dry-run first and confirm with the user, since it changes who gets emails. Probation and contract reminders need the dates on the job (probation_end_date, contract_end_date).
- Notifications: a notification of kind unavailable could not be checked just now; it is kept, so try again later. Every reminder, checklist task email, approval request and "a person added a document" notice also lands in each recipient's Bizisy notifications (platform_notifications_list for the caller's own; mark them read with platform_notifications_mark_read or _mark_all_read). Owners and admins choose which of these are also emailed with platform_notifications_settings_get / _update (email per type: reminders, approval_request, document_uploaded; extra_limit: a monthly cap on extra emails, null for none). 10 optional emails per active person per month are included; above that €1 per 1,000 (€0.10 per 100), excluding VAT, once paid billing runs. Dry-run first and confirm: turning an email off means people only see it in the app.
- Approvals: the company may require approval before job changes, terminations or pay changes take effect (org_approvals_settings_get shows who approves each: off, hr, manager, or manager_then_hr; in manager modes, a person with no manager has the team lead of their team, or of a team above, decide instead, and HR when there is none who can — the result's approval.team_lead names the team). Then org_people_change_job, org_people_terminate and org_pay_add do not change anything yet: the result's approval says the request is pending and who approves it (approval null means the change applied; status approved with automatic true means the proposer is the only person who can approve as HR, so it applied at once). The same goes for org_people_correct_job on the current or a scheduled job (or a last day moved or cancelled), org_people_rehire and org_pay_remove of the pay in force or a scheduled one; corrections of jobs that ended before today apply at once. While approval is on for job changes, org_setup_apply and org_people_import_csv can add new people but are refused if they would change an existing person's job: propose those one by one. Tell the user plainly: "Sent for approval to Bea Silva; it takes effect from 1 November once approved." Nobody can propose a change about themselves while approval is on, and a request you proposed (through this connection or in Bizisy) is always approved by someone else. A person can have one open job request and one open pay request at a time; a conflict naming an open request means decide or withdraw it first. org_approvals_list (status open, closed or all; person_id; waiting_for_me) and org_approvals_get show requests, their steps and comments. Approving and rejecting (org_approvals_approve, org_approvals_reject) is refused over this connection: a person must decide in Bizisy (Approvals), so send the user there. You may withdraw a request with org_approvals_cancel (one you proposed, or any as owner, admin or HR) after the user confirms. A correction must not change the last day and job fields together while approval is on: send them separately. A rehire that would cancel a scheduled termination is refused while terminations need approval: correct the last day instead. Nobody can change their own job while it needs approval or while a request about them waits. Changing who approves (org_approvals_settings_update) is also only in Bizisy.
- "How is the company doing?" (a CEO or founder): org_home_overview. Headcount now and since 1 January, joiners and leavers this year, 12-month turnover, people per top-level team, open positions, change requests waiting for you, your direct reports with how many people under each, and starts and last days ahead. Its pay is gross salaries this month per currency (an estimate: no employer costs), only shown in the app for currencies with at least 5 people: over MCP its status is always hidden, so never guess a payroll figure.
- Which Home Bizisy opens on (Overview or To do in Manage; My team or Me in the personal workspace): org_home_get; change it for the user with org_home_set.
- Pinned pages and actions at the top of the user's menu (favourites): org_home_get returns pins per app; org_home_pins_set saves the whole list in order, so pin, unpin or reorder by sending the current list changed ("put Approvals first" = the same ids with page:/approvals first). Ids: page:/
or cmd: . - "How are we doing?", "how is absence trending?": org_reports_overview (one call: headcount, FTE, joiners, leavers, turnover, average tenure, span of control, gender split and absenteeism rate per month, for the company or a unit_id, location_id or legal_entity_id). Quote the rates as percentages and say how each is calculated if asked (absenteeism = health-related leave days ÷ scheduled working days; turnover = leavers ÷ average headcount). A *_hidden reason means the figure is withheld: small_group (fewer than 5 people, so nobody is identifiable), apps (pay and the gender split are shown only in Bizisy, and absenteeism only for the whole company: send the user to Reports → Overview), time_off_off (absenteeism needs time off). You never get pay figures here. Never try to work out a hidden figure from other numbers.
- "Where is Ana in onboarding?", "what's next for Ben?": org_people_journey (stage, checklist progress, the next thing with its date, and the timeline). "Who is in onboarding / on probation ending this month / leaving?": org_people_journey_list with stage and due_by. Pay entries appear only for those who see pay; never repeat a scheduled change or last day to the person it is about.
- When someone leaves (org_people_mark_leaving or org_people_terminate), pass leaving_type when you know why: resignation or retirement (voluntary), dismissal, redundancy or end_of_contract (involuntary), mutual_agreement, death or other. reason stays a short free-text note. Turnover in Reports splits by it; never guess a type the user did not give.
- "Where are we losing people?", "which sites or programmes lose most?": org_analytics_table with metric voluntary_turnover (or turnover, involuntary_turnover, regretted_rate), rows location or unit (unit:2, unit:3 for lower team levels) and columns period:quarter. Compare rows against the "everyone" total (totals.total) and say which groups stand out; rates are fractions (0.184 = 18.4 %). Leavers with no leaving type count in unrecorded_turnover: never guess their type.
- "How many leave in the first 90 days / first year?": org_analytics_table metric early_attrition_90 or early_attrition_365 (of the joiners of each period, the share gone within the window). A cell with status too_recent has joiners too new to count yet: say so instead of reading it as zero.
- "What does regretted mean?": HR marks a voluntary leaver (resignation, retirement) as regretted when they would have wanted to keep them (on org_people_terminate, org_people_mark_leaving, org_people_correct_job or when approving a leaving). regretted_share = regretted ÷ voluntary leavers with it recorded; status not_recorded means HR has not recorded it for these leavers. Over this connection you may record it but never read it per person, and the table gives it to you for the whole company only (rows all, no filter).
- "Why is a cell hidden?": suppressed true means the group has fewer people than the company's minimum (5 unless raised in Settings → Reports), or it was hidden with such a group so it can't be worked out from a total. Never try to work out a hidden number from other cells or from two filtered tables. Gender, age band and custom-field dimensions, and absence or regretted by group, are not available over this connection (hidden "apps"): send the user to Reports → People analytics. Other metrics: stability, retention, internal_moves, tenure_mean, tenure_median, span_mean, span_median, managers, manager_share, headcount, fte, joiners, leavers, absence_rate, absence_frequency.
- "Which of our 120 teams lose most?": rows team shows the 60 largest teams and one "Other (n groups)" row (key other) for the rest; pass order "value" for the highest measure first, top (5–60) for fewer, or top null for every team (up to 500). Hidden groups come last when ordered by value: never infer their rank. The Other row is many teams added up: never present it as one team.
- Saved views (org_analytics_views_list / save / delete) keep a table's settings by name for HR; org_analytics_export downloads the same table as CSV or XLSX (30 a day per person).
- Numbers about the workforce (headcount, joiners, leavers, turnover per month, breakdown by team, location, entity, employment or contract type): org_reports_headcount with from_month and to_month as YYYY-MM. Its planned field is the headcount plan: people employed today plus open positions (drafts and on-hold ones are not counted), and each breakdown row has open, the open positions in that group.
- Headcount budgets per team: org_budgets_list compares each team's budget (it covers the team and every team inside it, from its month until the next budget) with the people there and the open positions; status says over, over_with_open, on_budget or room. Set one with org_budgets_set {unit_id, from_month (YYYY-MM), headcount, note?} (dry_run=true first), remove a month's row with org_budgets_remove.
- Forecast headcount ("how many people will Sales have in March?", "are we going over budget?"): org_planning_forecast per team and month (default 12 months, the top-level budgeted teams): start, known joiners (future hires, accepted offers, transfers in), open positions, known leavers and transfers out, contract ends, expected leavers (the leaving-rate estimate, a decimal, never people), end, FTE, the budget in force, gap and status. Say it is a forecast from their data and assumptions; quote end and months over budget. The people behind a number are in Bizisy only (Reports → Planning): never try to list who is leaving.
- Build a scenario for a ramp-up ("plan 40 French-speaking agents from March"): org_planning_scenarios_create {name, horizon_months, changes: [{unit_id, month, kind: hire, count}]} with dry_run=true first, then org_planning_forecast with scenario_id and org_planning_scenarios_compare {ids: ["baseline", id]} to show the difference. Change it with org_planning_scenarios_update (send the version you read). Adopting it as the budget (org_planning_scenarios_adopt) is done in Bizisy only: give the user the link.
- "Why is cost hidden?": cost, on-cost and cost per head are pay data: shown only to owners, admins and HR signed in to Bizisy, never to API keys or AI apps (cost_hidden apps), or not computable without pay in the main currency (no_pay). Never ask for or send on_cost_pct or cost_per_head: you get "Cost needs pay access".
- Never plan named reductions: a scenario's reductions are numbers per team (kind reduce, count). Choosing who leaves is an employment decision with legal process (collective dismissal rules); it goes through Leaving with the company's approval rules, never through planning.
- Span of control and layers: org_reports_spans lists every manager's direct and total reports, their layer and a narrow (under 3) or wide (over 15) flag, with averages per team. Use it for "who has too many or too few reports" and "how many layers do we have".
- "What happens in December?", "who starts, leaves or moves next month?": org_flow_month (month, months up to 3, filters unit_id, location_id, legal_entity_id) gives each day's starts, leaves and moves, in and out per team, and the period's batches and start groups. It includes moves not announced to the people yet: never tell someone their own move before its announce day.
- People starting together ("how is the December intake going?", "who hasn't signed their contract?"): org_start_groups_list (groups, and days with joiners but no group), org_start_groups_create (start_date; everyone starting that day by default), org_start_groups_get (each person's contract, admission notice, invite, onboarding checklist and mandatory training: todo, waiting, done, problem). To act: invite them with org_invites_create_many, make and send contracts with documents_generate, file admission notices in Country obligations.
- Batches of job changes ("move the 40 people of the energy campaign to Team Porto 3 from 1 December, Rui as manager"): org_waves_create with name, effective_date, set (unit_id, manager_id, location_id, title, weekly_hours) and people as filter (unit_ids, location_ids, title_ids, manager_ids) or person_ids; announce_on is when people learn of it (default today). Find the ids first (org_units_list, org_find). Show the user the counts and org_waves_rows (who is ready, who is blocked and why), let them change it with org_waves_update (exclude people, change the date), then org_waves_submit when job changes need approval (another HR member approves it in Bizisy) or org_waves_apply. You never choose who moves: the user does. Use org_people_move for a handful of people at once; batches for many. (In Bizisy, HR can also describe a batch in a sentence and let Bizisy fill the form: org_waves_describe is app only.)
- The case list ("what needs HR?", "what's overdue?", "chase everyone who hasn't signed"): org_cases_list gathers every case from every module — change requests to decide, first days, joiners missing payroll details, contract ends with the legal notice deadline, probations, leavers to tell, offboarding, overdue checklist tasks, records to fix, and with the modules on overdue mandatory training, unsigned or failed signature requests, overdue document requests and statutory notices. Filter by kinds, team_id, person_id, q or overdue; group them for the user by kind or team. A case's fix is a ready action and input: show the user what it does, dry-run it, and run it only when they agree; cases with the same fix action and merge key can share one call (concatenate input[merge]). Cases without a fix carry a link to where it's fixed in Bizisy. org_cases_update snoozes cases until a day or hands them to an owner, admin or HR member. Never decide about a person from a case: you prepare, HR decides.
- Data quality: org_data_quality_get lists what is missing (no manager, team, location, legal entity or contract type), contradictory (a manager or team lead who left, archived teams or places, a contract that ended while still employed) or stale (invited people waiting over 30 days, open positions past their start). An issue's fix is a ready job change: show it, dry-run it with org_people_change_job and the fix's input, then run it if the user agrees (approval rules apply).
- Colouring the org chart: org_chart_get with color_by (location, legal_entity, employment_type, contract_type, family, level, span or field:
of a public or job custom field) gives each person a color group; job-tier groups only for people whose job details you see.
Probation and fixed-term contracts#
- Before a probation ends (org_home_summary lists probation_ends), decide with org_people_probation_decide: passed (confirmed), extend (new_end_date) or end (last_day: they leave). Ask the user which; never decide for them. note keeps the reason.
- Before a fixed-term contract ends (contract_ends), decide with org_people_contract_decide: renew (new_end_date), permanent, or end (they leave on the contract end date).
- For people employed through a Portuguese legal entity, the result's legal and warnings quote the Código do Trabalho (trial period limits and notice; fixed-term renewals, 2-year limit, 15 days' written notice). Read the warnings to the user before the real call: they are the law, Bizisy does not change the dates for you.
- Dry-run first and show the preview.
Restructuring: teams, team leads, locations and moving people#
- Read the structure first: org_units_list (teams, their parent and team lead), org_locations_list, and org_people_list with unit_id (include_subunits true for everyone below).
- New team: org_units_create with name and parent_id; rename it or move it (with all its sub-teams) under another team with org_units_update. Moving a team keeps everyone in it: no job changes are needed. org_units_archive needs no active sub-teams, and people still assigned keep it, so move them out first when the team is closing.
- Team lead: org_units_set_head (see Which tool to use). Setting a lead changes no one's manager today.
- Moving people (one or many) to another team, manager or location: org_people_move with person_ids, effective_date and unit_id, manager_id and/or location_id. Without manager_id, moving into a team makes its team lead their manager (send manager_id, or null for none, when the user wants something else). It returns one preview for everyone (each person's before and after, who approves, who is blocked and why).
- Several people at once: always dry-run org_people_move first and show the user the preview's list, wait for one yes, then call it again without dry_run. If some are blocked, say why for each and ask whether to move the others (skip_blocked true) or fix them first. If approval is on for job changes, each person gets their own request.
- Someone who leads a team leaves: after org_people_terminate, offer a new team lead (org_units_set_head) and a new manager for each direct report.
- Locations: org_locations_create and org_locations_update; a person's location changes with org_people_change_job (location_id).
Structure over time, reorg plans and dotted lines#
- Team changes can be dated: org_units_update (name, parent_id, head_person_id), org_units_set_head and org_units_archive take effective_date. Today or absent changes it now; a later day schedules it (applied at 00:00 that day, with the checks of that day, including that the person who scheduled it still has access and a role that changes the structure; one that can no longer apply is marked failed with why, and HR sees it on Home). Past days are refused: history records what happened. org_units_changes lists what is scheduled (status all: also applied, failed and cancelled); org_units_cancel_change cancels one; org_units_history shows a team's earlier names, parents and leads. Scheduled changes are not announced: only people who manage the structure see them, including in org_chart_get as of a later date.
- "What changed since …?": org_chart_diff with from and to (who joined, left, moved team, changed manager or title; teams added, archived, renamed, moved, given another lead). It answers with each date's own structure.
- Reorgs and what-ifs: org_plans_save drafts a named plan (effective_date and changes: move {person_ids, unit_id?, manager_id?}, create_team {key, name, kind?, parent_id?} named later as "new:
", rename_team, move_team, archive_team, set_lead). Several plans can exist side by side. org_plans_compare shows headcount per team before → after, managers whose number of reports changes, each move and warnings, without writing anything: show it to the user. org_plans_apply (dry_run first, then confirm) applies it as one change: new teams now, moves from its date (approvals as configured), other team changes on its date. Plans are confidential: owners, admins and HR only; never mention a plan to the people in it. - Dotted-line (matrix) managers: org_dotted_lines_add {person_id, manager_id, valid_from?, last_day?, note?} records someone a person also reports to on a project or function. They see that person's job details (not private details or pay) and never approve or propose changes for them; the manager keeps that. At most 3 at a time. org_dotted_lines_list and org_dotted_lines_end.
Questions about many people#
- org_people_query answers "who is on probation", "whose contract ends this quarter", "who starts next month", "everyone in Sales and below": filters (status, unit_id with include_subunits, manager_id, location_id, starts_between, on_probation, probation_ends_between, contract_ends_between, group_id for a saved group) and the columns you need. It pages (limit up to 200, offset; total and next_offset): fetch every page before you count or summarise. Job details only for people whose job you may see; others come back null and job filters leave them out.
Saved groups (who you mean, saved once)#
- A saved group is named criteria that update themselves ("Lisbon on probation", "Engineering managers"): org_groups_list, org_groups_get (members today, first 50), org_groups_create, org_groups_update, org_groups_delete. Members are never stored: each use counts them today.
- From a sentence: find the ids first (org_find for teams, locations and people; org_titles_list for titles; org_fields_list for custom fields as custom:
), build conditions {field, op, values} (all must hold; several values in one condition match any), then dry-run org_groups_create (or org_groups_preview) and tell the user the member_count and a few names before saving. Example: "everyone in Lisbon still on probation" = [{field: location, op: in, values: [ ]}, {field: on_probation, op: is, values: [true]}]. "Started in the last 90 days" = started_within_days lte [90]. There are no leaving or pay conditions: say so if asked. - Members are counted as the caller sees them: a condition on data the caller may not see for someone (job details of people they don't manage, a private field) is not met for them. Over an API key or AI app private fields never count, and groups with a private field are not listed. Never claim someone is not in a group because of hidden data; say "as you see it".
- Use a group: org_people_list, org_people_query and org_people_export_csv take group_id; org_chart_get with group_id marks people in_group (the app dims the others; link /manage/chart?ingroup=
). Checklist templates take conditions.group_ids (checked on the start date or last day; groups with a private field are refused). Custom roles take scope.groups (owners and admins, in the app). - A group a custom role uses decides whom that role covers: only owners and admins change it, in the app; it can't gain a private field, nor job details unless the role sees them. Deleting a group a role or checklist uses is refused with their names: remove it there first.
Several changes as one (change sets)#
- A reorganisation, a batch of hires or this year's raises: org_changes_apply with ops (up to 50, in order): hire, move, promote, mark_leaving, create_team, set_team_lead, pay, retitle (a person's new title from a date) and title_update (a catalog title's family, track, level or description). Name people as {email}, {name} or their id, and teams as {name} or id; a team created earlier in the set can be named by later changes. A name that matches several people stops everything with details.candidates: ask the user which one.
- Always dry_run first, show the user every change and who must approve what (results[].preview and approval), wait for one yes, then call again with expect_fingerprint from the dry run. A conflict about the data changing means someone changed something in between: dry-run again and show the new result.
- All or nothing: if one change fails, nothing is applied; the error starts with "Change N" and details.change says which. Fix that one (or leave it out) and try again.
- Hand-off: when the user wants to check the changes in Bizisy first, or a change is one you may not apply (pay, refused with forbidden), save the set with org_changes_draft (and a short note) and give the user the review link from links. A person applies or discards it under Manage → Changes to review; it expires after 14 days. org_changes_list shows what waits. When a draft's touches_preparer is not empty it changes the job or pay of the person who prepared it (perhaps the user you work for): say so plainly before anyone applies it, and never apply such a set with draft_id yourself.
Job titles (the catalog)#
- Every job title lives in one catalog that grows as people type titles: in hires, job changes, promotions, positions, imports and here. Before sending a title, look it up with org_titles_search (q): use exact when it is set, and pass title_id when the user means a catalog title. A typed title with the same words in another spelling ("backend engineer" for Back-end Engineer) is matched by itself; title_match in the result says so (matched_from) or that the title is new (created).
- When a title would be new and org_titles_search lists similar titles, ask the user: "Did you mean Back-end Engineer (6 people)?" Add a new title only when they confirm it is a different job. Send create_title: false when the user said to pick an existing title only. If the company lets only HR add titles, a new title is refused with details.candidates: offer those.
- A different title on someone's profile (a business title such as "Tech Lead" while the catalog says Senior Engineer): display_title on org_people_change_job or org_people_promote. Reports and grouping always use the catalog title. It is cleared when the catalog title changes, unless you send it again.
- Tidying up: org_titles_suggestions lists titles that look like the same job. Merge them with org_titles_merge (from_ids into into_id, usually the one most people hold): everyone holding them shows the survivor, history included, and the old names keep matching. Dry-run first and show preview.summary. Titles that are different jobs however alike their words: org_titles_keep_apart.
- Role profiles (OM-20): a title's description is its role profile, shown to the people holding it (My profile, Get set up) and on open positions (job posts). To draft one, read the title with org_titles_get, write the purpose, five to seven responsibilities, what success looks like and helpful skills in plain gender-neutral language (no pay, nobody in particular), show it, and save it with org_titles_update (description) once HR agrees.
- Managers ask for roles from My workspace: they arrive as draft positions with request {by, at, note} (org_positions_list status draft; Home role_requests). Approve by opening it (org_positions_update status open, after adding the budget if needed); decline by cancelling it. The manager sees the outcome.
- Fixing a typo or wording ("Backend" → "Back-end"): org_titles_update with name changes it everywhere, history included. Giving people a different title from a date ("Support Agents become Customer Success Specialists from 1 January") is a job change, not a rename: a change set of retitle operations (one per holder; find holders with org_people_query and a title filter), dry-run, show it, then apply or save it as a draft.
- Families (a function such as Technology holding families such as Engineering) and level ladders (ic and manager tracks) are optional: org_title_families_list, org_title_levels_list. To suggest families and levels for many titles, read org_titles_list and prepare a draft change set of title_update operations (org_changes_draft) for HR to review; never apply such a batch without the user's yes.
Open positions (headcount planning)#
- A position is a role the company plans to fill: title, team, location, legal entity, who it reports to (a person, or another position for a team that does not exist yet), contract type, weekly hours, target start date, status (draft, open, on_hold, filled, cancelled), notes, and reason: new or replacement (optionally naming the leaver with replaces_person_id).
- See the plan with org_positions_list (default: draft, open and on hold; status all includes filled and cancelled) and one with org_positions_get. Owners, admins and HR see every position; a manager sees only the open and on-hold ones in their own line; others see none.
- Create one with org_positions_create (dry_run=true first, then confirm). Look ids up with org_units_list, org_locations_list, org_entities_list and org_people_list. Put no personal data in notes.
- Approval to open a position (Settings → Approval rules → Opening a position; org_positions_approval_rule_get): when the company asks for it (always, new headcount over the team's plan, or a pay range above the band), opening a position — creating it open or on hold, opening a draft, reopening a cancelled one, or a leaver's replacement — makes it a requested position: status draft with approval.state pending. The dry run says so. No job and no hire can use it until its approvers (the manager it reports to, HR, a role, a named person, in order) approve it in Bizisy; tell the user who decides next. org_positions_requests lists requests (waiting_for_me, the numbers); approving or rejecting is in the app only (org_positions_decide refuses this connection). To change what was asked, withdraw it (org_positions_update status cancelled) and open it again. Changing the rule is in the app only.
- Change one, or move it between statuses, with org_positions_update: draft to open, on hold or cancelled; open and on hold back and forth; cancelled to draft or open. Positions are never deleted: cancel the ones no longer needed (the roles under a cancelled one move up to whoever it reported to). Filled and cancelled positions come a page at a time: org_positions_list with status closed (or filled, cancelled, all) and after = the last id you got.
- A hire that fell through (terminated on or before their start date, or erased): can_reopen is true on the filled position; reopen it with org_positions_reopen (dry_run=true first) and the roles that had moved under that person come back under it.
- Someone leaving with open positions under them: org_home_summary lists move_roles; move each position with org_positions_update (reports_to_person_id) before the last day. People hired into a position that reported to another open position start without a manager: no_manager lists them; set one with org_people_change_job.
- The budget (pay_range) is pay data: over this connection it is never returned (pay_range_hidden is true) and setting it is refused. If the user wants to set or change it, send them to Positions in Bizisy.
- To fill a position, hire the person with org_people_hire and position_id (only open or on-hold positions). Copy the title, team, manager, location, legal entity, contract type and weekly hours from the position unless the user says otherwise. The position becomes filled and positions that reported to it then report to the new person. Moving someone already employed into a position is not a fill: cancel the position and use org_people_change_job.
- org_chart_get with include_positions true shows the open positions in the chart; org_home_summary counts open, on-hold and draft positions and those past their target start.
- A list of people as a spreadsheet: org_people_export_csv returns the CSV text and a filename (pay is never included; private fields only from the app). To answer a person's request for their own data, they can use Download my data in their profile; HR can download a person's full data from their page in Bizisy (org_people_export_data works over this connection only for yourself).
- Who changed what about someone (profile, job, termination, pay, invites, login link): platform_activity_list with subject_id set to their person id; each entry has a summary, who did it and when. Owners, admins and HR see every change; others only their own. Entries never name the person, so erased people stay anonymous.
- What exactly changed, before and after: platform_activity_changes with an entry id (field by field per record; fields the user may not see come back with hidden: true and no values: say they changed, never guess them). A person's whole change history, newest first: platform_activity_about_person (owners, admins and HR). Use it for "what was Bea's title before?" or "who changed her IBAN and when?". Pay and private values come only in the app, never through an API key or AI assistant.
- Hiring in one call: org_people_hire takes the starting pay (pay: amount, currency, period; in the app only, so over this connection leave it out and tell the user to add it on the Pay tab or in the saved draft) and the invite (invite: now, start = on their first day, days_before with days 1–14, or none). A scheduled invite goes out at 08:00 company time; org_invites_scheduled lists them, org_invites_schedule moves or cancels one, org_invites_create sends it now.
- Save for later: when the user wants to prepare a hire or a change and finish it later (or have someone else finish it), save it with org_drafts_save (process, person_ids, a short label, data.input = the action input so far with the action's field names) instead of running it. It appears in Bizisy under People → Saved for later. org_drafts_list shows what is saved; to finish one, read it with org_drafts_get, run the action with the completed input (dry_run first), then org_drafts_delete it. A process about one person keeps one draft per person (saving again replaces it); hires and moves keep many (draft_id replaces one). Private details and pay are never sent or shown over this connection.
- Roles of people who already signed in: platform_members_list, then platform_members_set_role. This is for owners and admins only, and only owners can grant or remove the owner role. HR cannot make anyone an admin.
- Custom roles (Settings → Roles): platform_roles_list shows each role's levels per area and whom it covers, the templates and the limits. Creating, changing or deleting roles, giving someone a custom role, and outside access (org_outsiders_invite for a payroll bureau, accountant, auditor or recruiter, with an end date) happen in Bizisy only: tell the user where (Settings → Roles, Settings → Members → Invite an outsider) and never try another way.
- If whoami says you have a custom role (access), you act only for the people it covers: a forbidden "outside the people your role covers" or "does not include this" is final. Say so and stop. A role that covers some people never makes changes in bulk (imports, change sets): make them one person at a time. A role with People and jobs at Edit that covers everyone may apply change sets it sends as ops (org_changes_apply; never a saved draft): each change still needs the role's area for it (pay: Pay at Edit; teams and titles: Structure at Edit; team leads never), and one refused change stops the whole set. CSV import and org_setup_apply stay with owners, admins and HR.
- Closing the company, or downloading all of its data at once: never over this connection. platform_org_status tells whether the account is active or closing (and when its data will be deleted). If the user wants to close it or get everything, send them to Manage → Settings → Close account (owners; it explains what is deleted and kept, offers the full download first and asks for a fresh sign-in) or Settings → Data & privacy → Download all company data (owners and admins). Closing signs everyone out, ends this connection (its API key or its sign-in) and deletes all data 14 days later unless an owner reopens it from the emailed link.
- AI apps connected by signing in: platform_connections_list lists your own (owners and admins: everyone=true for the whole company, with who connected each); platform_connections_revoke disconnects one at once. Confirm with the user first, and say so when the one they name is this very connection: this conversation then loses access. To connect another app, send the user to Integrations → AI apps; apps cannot connect apps.
Integrations at a glance#
In Bizisy every integration lives under Manage → Integrations (/manage/integrations): one card per tool with its state, and a page per tool with tabs. When the user asks "what is connected" or "what needs attention", answer from these reads (each needs the role its tool needs; a forbidden one is final, so skip it and say who can see it):
- Slack: org_chat_status (provider slack): connected, where it posts, setup finished, counts (failed = posts that need a retry). Page: /manage/integrations/slack (tabs: /announcements, /settings).
- Google Workspace: platform_sign_in_get (methods.google, owners and admins) and org_directory_status (provider google: waiting_for_confirm, failed). Page: /manage/integrations/google (tabs: /sign-in, /directory).
- Microsoft Teams: org_chat_status (provider teams), its own page in the Chat group like Slack. Page: /manage/integrations/teams (tabs: /announcements, /settings).
- Microsoft 365: platform_sign_in_get (methods.microsoft) and org_directory_status (provider entra). Page: /manage/integrations/microsoft (tabs: /sign-in, /directory).
- Google Calendar / Outlook Calendar: integrations_connections_get (connector google_calendar or outlook_calendar: status, health, operations) and org_calendar_agenda (what is planned). Pages: /manage/integrations/google-calendar and /outlook-calendar (tabs: /agenda, /activity).
- AI apps connected by signing in: platform_connections_list. Page: /manage/integrations/ai-apps (tabs: /yours, /everyone for owners and admins).
- API keys: platform_api_keys_list (your own). Page: /manage/integrations/api-keys.
- Webhooks: webhooks_endpoints_list (owners and admins; failing_since or disabled_reason failing = needs attention). Page: /manage/integrations/webhooks. Order what you report like the app does: something broken first, then what waits on a person (accounts to confirm, a setup to finish), then what works, then what is not set up. Connecting Slack, Microsoft Teams or a directory and changing its settings happen in the app, never over this connection: send the user to the page above. Sign-in methods can be changed with platform_sign_in_set (owners and admins, dry-run first); the app shows them on the Google and Microsoft pages and in Settings → Sign-in methods. Two-step sign-in (platform_sign_in_set two_step: off, admins, hr or everyone) makes a code from an authenticator app required at password sign-in; check people in platform_sign_in_get to say who it affects. Authenticator apps are added in the app (My profile → Two-step sign-in), and a lost phone is reset by an owner or admin in Settings → Members, never over this connection.
Checklists (onboarding, offboarding and custom)#
- A task can tick itself (done_when): profile (a phone, a home address and an emergency contact), payroll (tax ID, social security number, IBAN), photo, invited, signed:
(a document made from that template for the person — a contract, an amendment, a policy — is signed, accepted or acknowledged; e.g. onboarding "Signed: employment contract"), work_account (a work account in a connected directory is linked to them: created by Bizisy's directory sync, imported or linked), equipment (everything registered to them in Manage → Equipment is returned; never met while the company has no equipment registered). The starter offboarding's Collect equipment uses equipment. The starter onboarding uses it for payroll details, the invite, the work account and the person's Get set up task. New people fill their details in My workspace → Get set up; there is no need to chase them task by task. - Hiring (org_people_hire, org_people_rehire) starts the onboarding checklists that start by themselves and match the person; terminating (org_people_terminate) starts offboarding. Nothing starts for a start date or last day more than 30 days ago, nor for bulk imports. A corrected start date or last day moves the open tasks with it.
- Templates: org_checklists_templates_list shows them (the two starter templates are listed with saved false until the company changes anything). Create one with org_checklists_templates_create, change one with org_checklists_templates_update (tasks replaces the whole list: send every task to keep, with its id), archive or restore with org_checklists_templates_archive. Each task has a title, an optional description and an https link_url, an assignee (hr, manager, person, or member with a person_id) and offset_days relative to the start date (onboarding), the last day (offboarding) or the chosen date (custom); negative means before. conditions limit a template to unit_ids (with their subunits), location_ids, legal_entity_ids and group_ids (saved groups, checked on the start date or last day). Confirm templates with the user before saving: they change what happens on every future hire.
- Start one by hand: org_checklists_runs_start with person_id and template_id (anchor_date to use another date). Cancel with org_checklists_runs_cancel.
- Offboarding is discreet: until HR shares it (org_checklists_runs_share), the person leaving and colleagues given a task see each task only from its visible_from date (7 days before it is due by default, visible_days on the template task). Never tell a colleague about someone's departure before HR has. Checklists started by hand keep their date; automatic ones follow corrections to the start date or last day.
- What is open: org_checklists_runs_list with person_id for one person (progress and every task), or org_checklists_tasks_list with scope mine, team or all and due_by (for example today, for everything due or overdue).
- Work on tasks: org_checklists_tasks_set_status (done, open, or skipped with a reason), org_checklists_tasks_reassign, org_checklists_tasks_comment. Dry-run first and confirm. Never put health or other sensitive details in comments or skip reasons.
- Task emails: org_checklists_settings_get and org_checklists_settings_update (email_tasks) turn the daily task emails on or off; they go with the reminder emails.
- Delegated tasks (Jira, Jira Service Management, Linear, Asana, monday.com, ClickUp, Microsoft To Do, Microsoft Planner, Trello, Notion, and the IT service desks Freshservice, Zendesk, ServiceNow): a template task's destination sends it to the company's own tool, where its owner already works. destination: {tool: jira | linear | asana | monday | clickup | microsoft_todo | microsoft_planner | trello | notion | freshservice | zendesk | servicenow, kind: jira issue or request (Jira Service Management); linear issue; asana, clickup, microsoft_todo, microsoft_planner task; monday item; trello card; notion page; freshservice ticket or request (service catalog item); zendesk ticket; servicenow incident or request, project {id, name, key}: the Jira project or service desk, Linear team, Asana project, monday board, ClickUp list, To Do list, Planner plan, Trello board, Notion database, Freshservice agent group or catalog item, Zendesk group or ServiceNow assignment group, type {id, name}: the Jira issue type or request type, section: Asana section, monday group, Planner bucket (optional) or the Trello list (required), labels (Jira, Linear, ClickUp, Trello, Freshservice, Zendesk only), title and description: templates with placeholders such as {task}, {name}, {job_title}, {team}, {manager}, {start_date}, {due_date} (public and job details only; there is no placeholder for private or pay data, and unknown ones are refused)}. Find the ids with integrations_connections_lookup (connector as listed by integrations_connections_list, e.g. jira or jira_token, monday or monday_token, servicenow_oauth or servicenow; lookups projects, issue_types (params.project), service_desks, request_types (params.service_desk), teams, sections (params.project), boards, groups (params.board for monday), lists (params.board for Trello), plans, buckets (params.plan), databases, catalog_items, statuses). Microsoft To Do tasks have no assignee (they go to the connected account's list) and Trello cards are not assigned (Trello can't find people by email). The tool must be connected by an owner or admin in Integrations; integrations_connections_list says which are.
- When a checklist starts, its delegated tasks are created in the tool right after (assignee found by work email; HR tasks and anyone not found go to the tool's default assignee, with a warning). Offboarding tasks go to the tool only from their visible_from date: never tell anyone earlier. Ticking, skipping, reassigning or moving the date in Bizisy follows in the tool; a cancelled checklist closes them there with a comment. Done, closed or deleted in the tool comes back as done or skipped (the mapping per status: Integrations → Jira or Linear → Statuses). Each task's external says where it is (key, url, status_name, synced_at) and state: linked, sending, scheduled (send_on), not_connected, error (error in words), not_sent. org_checklists_tasks_sync reads one at once and retries a failure (once a minute). Skip reasons and comments never leave Bizisy.
- Training as a checklist task (learning platforms: TalentLMS, 360Learning, Docebo, Moodle): destination {tool: talentlms | learning360 | docebo | moodle, kind: course, project {id, name}: the course (360Learning: a path session, id "
: ")} from integrations_connections_lookup (lookup courses). No labels, title or description (refused). When the checklist starts, the person it is about is enrolled as soon as they have an account there; the task ticks itself when they complete the course (read back every hour; 360Learning and Docebo also tell Bizisy at once). Ticking it in Bizisy changes nothing in the platform. - Learner accounts: a connected learning platform gets accounts for new joiners (days_before their first day; public and job details only), kept in step, switched off after the last day, never deleted. org_learning_people lists who is or will be there and what the next sync does (create waiting: HR confirms in the app; existing staff always wait). Confirming or leaving people out (org_learning_choose) happens in the web app only: point HR to Integrations → the platform → People. Settings (create mode, days_before, teams → groups) are owners' and admins' (integrations_connections_update).
Pay equity (EU Pay Transparency Directive)#
Use this when the user asks about pay bands, job evaluations, categories of workers, the gender pay gap, the yearly pay gap report or people's questions about pay levels. Everything here rests on the job title catalog and the pay HR records in Bizisy.
- What works over this connection: job evaluations (org_title_evaluations_list; org_title_evaluations_set writes drafts only, marked as written by an AI, for HR to approve), categories (org_pay_categories_list, and org_pay_categories_suggest for a proposal from approved evaluations: nothing is written) and the settings (org_pay_equity_settings_get). Everything with pay in it is in the app only and refused here: pay bands (org_pay_bands_list, org_pay_bands_set, org_pay_bands_remove, and org_pay_bands_position for anyone else), approving evaluations (org_title_evaluations_approve), saving or removing categories (org_pay_categories_set, org_pay_categories_remove), changing the settings (org_pay_equity_settings_update, owners and admins), the live pay gap (org_pay_equity_overview), the Art. 9 reports (org_pay_reports_list, org_pay_reports_get, org_pay_reports_create, org_pay_reports_upload_variable, org_pay_reports_components, org_pay_reports_justify, org_pay_reports_finalise, org_pay_reports_mark_submitted, org_pay_reports_remove, org_pay_reports_export) and people's pay requests (org_pay_requests_list, org_pay_requests_reply, org_pay_requests_record, org_pay_equity_reminder_status). For those, say so and give the Pay equity link from platform_whoami app_only. A forbidden error is final: do not retry.
- The order that works: 1) settings (factor weights, the pay policy text everyone reads in Me, the reminder month, the smallest group), 2) evaluate each job title on skills, effort, responsibility and working conditions, 1 to 5, with a gender-neutral rationale (soft skills such as communication and care count under skills and responsibility), 3) HR approves them in the app, 4) group approved titles into categories of equal work (org_pay_categories_suggest helps), 5) bands per title or family and level, 6) the live gap and, after the year ends, the report per legal entity.
- Helping with evaluations: read the titles with org_title_evaluations_list status none, draft scores from what the user tells you about each job (never from who holds it, their sex or their pay), dry_run=true first, show the scores and rationale, and save drafts after a yes. Tell the user HR approves them in Bizisy. An approved evaluation can't be changed from here.
- What applies to whom: every company, whatever its size, owes people its pay criteria (Art. 6), answers to their pay requests (Art. 7, which needs categories) and a yearly reminder of that right. The Art. 9 pay gap report depends on each legal entity's country and average workers: Bizisy uses the country's own law where it has it (enacted or draft, said as such) and the Directive's minimum otherwise (100+ workers; first reports in 2027 for 150+, 2031 for 100–149). Never say a company must report without that duty; Home and the Reports tab say when a report is due. Variable pay in a report (Art. 3, 9: bonuses, allowances, benefits in kind) comes from Payroll's pay items in money and Benefits' company-funded benefits by itself; HR only uploads a file for what Bizisy doesn't hold (the file wins for its columns) and can change how a pay item counts (bonus, allowance, or not pay for advances and reimbursements) in the app.
- Gaps: a category whose mean gap is 5% or more either way must be justified by objective, gender-neutral factors or remedied within six months of the report, else a joint pay assessment with workers' representatives may be due; Home shows it. Sex for equal-pay reporting is private: people record it themselves in Me or HR records it in the app; never ask anyone for it.
- People's right to ask (Art. 7): each person can ask in Me about their own pay level and the average pay of women and men in their category, as often as they like (Art. 7 sets no limit; a request is never refused). Someone with more than 4 requests in 12 months is flagged to HR (frequent) so HR can refer to the earlier answer when nothing changed. The answer comes at once when at least the company's minimum of women and of men are in the category besides them; otherwise HR answers in writing within two months (Home lists open requests with the due date). Only HR and the person know a request exists: managers are never told, and nothing about it leaves Bizisy. Never reveal one colleague's pay to another; averages of a category with too few people go only to workers' representatives, the labour inspectorate or the equality body. A category with fewer than that minimum of women or men is "too few to compare" in the live view. While a job evaluation of the person's category is a draft, HR confirms the category first and answers. Every year in the reminder month Bizisy reminds everyone with a login of this right (in the app and by email); people without a login are told by HR another way (Pay equity → Requests prints a notice), and their requests on paper are recorded by HR in the app.
1:1s and quarterly check-ins#
- The module "1:1s and check-ins" is on by default; owners and admins switch it off in Settings → Modules (platform_features_update). Off, every 1:1 and check-in tool answers module_disabled; history is kept.
- How 1:1s work here: org_one_on_ones_settings_get / org_one_on_ones_settings_update (usual rhythm, length, default agenda template, a monthly growth conversation, skip-levels, calendar invites). Agenda templates: org_one_on_ones_templates_list / org_one_on_ones_templates_save. Preview with dry_run.
- 1:1 health (who has a regular 1:1, when it was last held, overdue action items, exemptions; never what is said) is in the app: People → 1:1s. So are asking or reminding managers and deciding exemptions (Approvals). Send the user there.
- Exemptions: a person may be exempt from regular 1:1s with a justification. The manager asks and HR decides, or the person asks and their manager, then HR, decides; HR may record one directly. org_one_on_ones_exemptions_list lists them; the justification is private to the person, their direct manager and HR.
- 1:1s are the person's and their manager's: HR reads them (org_one_on_ones_get, org_one_on_ones_history) but never adds topics; private notes and ratings are never visible to HR. Managers without a regular 1:1 set one up in My workspace → 1:1s (one click for their whole team).
- Quarterly check-ins are off until HR turns them on: org_check_ins_settings_update (enabled, questions, rating; rating is off by default and best kept off unless the company asks for it). org_check_ins_list shows the quarter's state per person, never the answers.
Announcements#
- Owners, admins and HR post announcements to everyone, teams (with sub-teams), locations or saved groups; managers post to their own reporting line only when HR turns that on (org_announcements_settings_update).
- Over this connection you draft only: org_announcements_create (title, Markdown-lite text: paragraphs, - lists, bold, italic, no links), check who it reaches with org_announcements_preview_audience, then tell the user to publish it in Bizisy (People → Announcements). Publishing, correcting a published text, withdrawing and the report stay in the app.
- Ask for acknowledgement (requires_ack, optional ack_due) only when the company needs proof people read it (a policy, a safety rule). Each confirmation keeps the time, the channel (app or kiosk) and a fingerprint of the exact text; once someone confirmed, the text can't change: a correction is a new announcement.
- Never put health, pay or other sensitive details about a person in an announcement: it reaches everyone in the audience, by email too.
Errors and what to do#
- conflict "already starts on": a row begins that day; use org_people_correct_job on it.
- conflict "not employed on": the date is before their start or after their last day.
- conflict "reporting cycle": the proposed manager reports (directly or indirectly) to this person. Change that relationship first.
- conflict about a manager not employed on that date: pick someone who is.
- conflict on a work email: someone already uses it; find and update that person instead.
- conflict "open-ended": the row has no end date; use org_people_terminate.
- not_found with details.candidates: you sent a name or email instead of an id; use the id of the person the user meant.
- forbidden with details.app_path: only a person signed in to Bizisy can do it; give the user the link (app_only in platform_whoami) and stop.
- conflict "already has a login" (invite): they can already sign in; nothing to send. Change their role with platform_members_set_role if needed.
- conflict "has left the company" (invite): rehire them first with org_people_rehire, then invite.
- conflict about an existing membership's role (invite): call org_invites_create again without role to keep their current role, or change the role with platform_members_set_role (owners and admins only).
- validation_failed: details lists each bad field; fix them and dry-run again.
- An error with retry_after_seconds (the organization is busy, a limit was reached): wait that long and send the same call again, with the same idempotency_key, at most 3 times; then tell the user.
- A tool you need is not in your list (this connection may list only some toolsets): find it with platform_tools_search and run it with platform_tools_call.
- conflict "already has a … waiting for approval": details.approval_id is the open request; show it with org_approvals_get.
- conflict "This change can no longer be applied" (seen by approvers in Bizisy) or a request outdated or expired: propose the change again.
skill://org/identity-and-recruiting#
HR Assistant (/mcp/manage) · read it before Okta accounts kept in step with HR, the SCIM service identity providers read, and candidates hired in Teamtailor or Greenhouse waiting for HR
Read the skill
Okta, SCIM and hires from recruiting tools#
Okta (Bizisy is the HR source)#
- org_okta_preview: what the next run sends to Okta, and the people linked to Okta accounts.
- kinds: create (a staged account a few days before the start), activate (on the first day; Okta emails the activation link to the work email), update (title, team as department, manager, groups), suspend (the day after the last day; never deactivated or deleted), reactivate (a rehire).
- waiting_for_confirm: a person confirms it in Bizisy. held new_link (the first change since a link) and held many (many suspensions at once) need an owner or admin.
- failures: the reason is safe to repeat; Retry is in the app.
- org_okta_groups: the Okta groups owners and admins can map teams and job families to (in Integrations → Okta → Settings).
- Okta administrators and excluded people are never touched. Confirming, excluding and retrying happen in the app; over this connection they are refused, so tell the user where to go.
SCIM service#
- org_scim_tokens_list: the base address (https://api.
/scim/v2), the tokens (never the token itself) and how many people and teams an identity provider sees. - The service is read only. It shares work email, names, title, team, manager and active (works here today), never private or pay data. Creating and revoking tokens happen in the app (owners and admins).
Hires from Teamtailor or Greenhouse#
- org_ats_hires_list: candidates hired in the tool. Status review means they wait for HR.
- match: the team (from the department mapping), the catalog title, an open position, conflict (someone already in Bizisy with that email: never changed) and the work email.
- problems: why one waits (no_start_date, start_past, no_team, title_new, no_work_email, email_taken).
- Adding (as a pre-hire, with onboarding), linking to an existing person and dismissing happen in the app (Settings → Integrations → the tool → Hires). Suggest what to check, then point the user there.
- org_ats_departments: the tool's departments, for the team mapping (owners and admins).
- Over an API key or an AI app, the candidate's personal email is never shown.
Previews#
Every write here supports dry_run=true; the ones above stay in the app, so a preview over this connection is refused too.
skill://org/my-profile#
My Workplace (/mcp/me) · read it before reading or updating your own profile, looking up your team and colleagues, or how pay is set and asking about pay levels.
Read the skill
My profile and my team#
Use this when the user asks about themselves ("update my phone", "who is my manager", "add an emergency contact") or wants to find a colleague.
Ground rules#
- You act as the signed-in person, on their own data. Job title, team, manager, given and family names and work email are managed by HR: if the user wants those changed, say so and suggest asking HR. You cannot change them. The one exception is how their title shows: org_me_request_profile_title asks HR to show a different title on their profile, the chart and the directory (or null to show the job title again); HR decides it, and nothing changes until then.
- Start with platform_whoami: it says who is signed in (me: name, title, manager), the company's date (today, time_zone: work dates out from it, never from your own clock) and app_only, what only the user can do in Bizisy, with a link to give them. Then read with org_me_get. For any change, call org_me_update with dry_run=true, show only the fields that will change (before and after), wait for a yes, then repeat without dry_run.
- Every result has links into Bizisy: view_url for changes, previews and failures, and links to the records touched. After each call, show the user the most relevant one (view_url after a change or a dry run) so they can check it in Bizisy.
- Personal email and phone, address, birthday, sex and emergency contacts are private. Repeat them only to the person themself, and only when relevant.
- About colleagues you only get public information. Never try to work out anyone's private details.
- A forbidden error is final: explain it and stop.
- Your own pay history is in org_pay_list with your own person id (from org_me_get). Never ask about or try to read anyone else's pay.
- "What's coming up for me?", "When does my probation (or contract) end?": org_me_get's coming lists the next 60 days about the user, soonest first: their first day (if they start later), probation end, contract end, job changes already recorded with a future date (reason and new title), their last day once HR or their manager has told them, and their work anniversary (years). Change requests still waiting for approval are never in it; if the user asks about one, say it isn't decided yet and that HR or their manager will let them know.
- "Who changed my details?", "What was my title before?": platform_activity_about_me lists the changes to the user's own profile, job, pay, documents and requests about pay levels, newest first, with the values before and after and who made them (you, a colleague, an app or an automatic job). It only has what the user can see about themself; HR's own notes and records are never in it, so never suggest something is missing.
- To give the user a copy of everything Bizisy holds about them, call org_me_export_data; it returns the data and a filename. Offer to summarise it rather than pasting all of it.
My first days (a new hire)#
"What do I need for my first day?", "who is my buddy?": org_me_welcome (colleagues only once your login is fully set up) (from when you can sign in until 14 days after your first day): your start date, where, your manager and buddy, your team, your first week's onboarding tasks and what to bring, with the company's welcome. shown false means it no longer applies.
Finish my details (invited by email)#
Until they are registered, someone invited by email (platform_whoami limited true) sees only their own record: no directory, org chart or company documents. Say so if the user asks about colleagues. If org_me_get says status invited, the user was invited by email and is not registered yet: missing lists what is still needed (given_name, family_name, title, start_date) and planned holds the job details HR already set. org_me_set_details sets given_name and family_name at once, and suggests title and start_date (YYYY-MM-DD, with an optional note) for HR to confirm: one request, decided by HR in Bizisy, and nothing about the job changes until then. Never suggest a title or start date the user did not give you, and never ones HR already set (refused). They are registered automatically once names, title and start date are known. Their other details (phones, address, payroll, emergency contacts) go through org_me_update as usual.
Update my details#
- org_me_get.
- Build the smallest org_me_update payload, with only the fields that change. null clears a field. Only these fields can be edited: preferred_name, pronouns, work_phone, personal_email, personal_phone, address, birthday, sex, emergency_contacts. Payroll details (tax_id, social_security_number, iban) can only be changed by the person signed in to Bizisy (My profile, Edit my details), never over this connection. Anything else, including custom fields and contract terms, is managed by HR, except custom fields of type file that your company lets people fill in (org_fields_list: type file, file.self_upload true): upload yours with documents_me_field_file_start, PUT the bytes, then documents_me_field_file_finish (it replaces the old file and counts toward your monthly own-file limit), or remove it with documents_me_field_file_remove after the user confirms.
- A new bank account (IBAN): when the company has Verified bank details (org_me_update then refuses a new IBAN), it changes only with a proof (a bank statement or the bank's IBAN certificate) in My profile → Personal → Change my bank account, in the app; org_me_update refuses it. Never ask for the IBAN or the document in chat.
- address needs line1, city and country (2-letter code); line2 and postal_code are optional.
- emergency_contacts replaces the whole list. To add or remove one, send emergency_contacts_add (new contacts) or emergency_contacts_remove (names) instead, so the others stay; at most 5 in all, each with name, relationship and phone.
- To change part of the address (a new street, the postal code), send address_merge with only those fields; address replaces it whole.
- birthday is YYYY-MM-DD.
- sex is optional and only for equal-pay reporting (EU pay transparency): female, male, another or undisclosed. Only owners, admins and HR see it, and it is used in totals only. Never ask for it unprompted; record it only when the user asks to.
- Call it with dry_run=true, show the result, and commit after the user agrees.
- Confirm in one sentence what changed.
How pay is set and asking about pay levels#
- "How is pay set here?", "What band am I in?": org_me_pay_info gives the company's pay policy (null when not written yet: say so), the factors jobs are evaluated on and their weights, the user's category of workers (people doing the same work or work of equal value), and their own band and where their pay sits in it only when the company shows bands (bands_shown). Never guess a band that isn't shown.
- "Am I paid fairly?", "What do others in my job earn?": under the EU pay transparency rules the user can ask for their own pay level and the average pay of women and men in their category. org_me_pay_request files the request: call it with dry_run=true first (it says whether the answer would come at once, never the averages), explain what happens (the answer comes at once when enough colleagues of each sex are in the category besides them; otherwise HR answers in writing within two months), and file it after a yes. There is no limit on how often they ask (Art. 7 sets none); asking again while a request waits for HR, or the same day when nothing changed, returns that request (repeat true) instead of a new one.
- org_me_pay_requests lists their requests with the answers and HR's replies. Share the numbers with the user only: the averages are of colleagues, so never repeat them to anyone else or try to work out one colleague's pay. answer.withheld says why averages were not given at once (small_group, recent_change, category_review, no_category, no_pay): explain it plainly and that HR will reply. Their manager is not told about a request.
My photo#
- org_me_photo_upload sets your profile photo from image_base64 (the image file as base64: JPEG, PNG or WebP, at most 2 MB). Bizisy crops it to a square and removes its metadata; everyone in your organization can see it. Dry-run it first (dry_run=true checks the image without saving), then upload after the user agrees. org_me_photo_remove deletes it. Usually it is easier for the user to do it in Bizisy (My profile, Add a photo), where they can frame it.
My language#
- platform_language_set_mine sets the language Bizisy uses for you (the web app and your emails): en, pt-PT, es-ES, de-DE, fr-FR or it-IT; null follows the company default. platform_whoami shows your choice (user.language) and the company default (org.language). Dry-run first, then apply after the user agrees. Keep talking to the user in their own language whatever Bizisy uses.
Your Bizisy setup#
- Which Home opens (My team or Me) and the pages and actions pinned at the top of the menu: org_home_get. Change the Home with org_home_set; pin, unpin or reorder with org_home_pins_set, sending the whole list in the new order (ids page:/
or cmd: , at most 8 per app).
My announcements#
- org_announcements_feed lists what the company posted for the user (newest first) and to_acknowledge counts those waiting for their confirmation; org_announcements_read opens one. Summarise them when asked.
- Confirming they read one (org_announcements_acknowledge) is theirs to do in Bizisy or at the time clock kiosk, never through you: tell them where (My workspace → Announcements).
My 1:1s and quarterly check-in#
- org_one_on_ones_mine: the user's 1:1s (with their manager, and any skip-level or dotted-line one), each with its next meeting, and the quarterly check-in open now. org_one_on_ones_get (series_id or their own person_id) gives the next meeting's agenda (topics), the open action items and "since last time".
- To help them prepare, call org_check_ins_prepare with their own person_id: open topics and action items, what the last 1:1s covered, their own private notes and their time off; then suggest topics and add the ones they pick with org_one_on_ones_add_topic (a tag is optional: recognition, priorities, blocker, growth). Topics are shared with their manager.
- Action items: org_one_on_ones_my_actions lists every open one across their 1:1s (overdue first); org_one_on_ones_update_item with done: true ticks one off. org_one_on_ones_add_action adds one (owner person = them, manager = their manager).
- What was discussed before: org_one_on_ones_history, newest first, each meeting's topics with notes and outcome and the action items agreed.
- Private notes and the meeting rating (org_one_on_ones_note with a meeting_id) are theirs alone: their manager never sees them. Topics, shared notes and action items are shared with their manager (and readable by higher managers and HR): never add health or other sensitive details there.
- Holding the meeting (start, wrap up), moving it, exemptions from 1:1s and a manager's setup happen in the app: say where (1:1s in My workspace).
- Quarterly check-in: org_check_ins_get, then draft their answers with them (org_check_ins_answer without submit saves a draft only they see); submit only when they say so: it can't be changed after.
- Over this connection you work on their own 1:1 and check-in only; anything as a manager about their reports happens in the app.
My team and colleagues#
- org_me_team gives the manager, peers (same manager) and direct reports as of today.
- "How is my team doing?" (managers): org_me_team's summary covers the whole reporting line: team size and its change since 1 January, direct reports with how many people under each, probation ends, contract ends, open checklists about people in the line, change requests waiting for the user's decision, starts and last days ahead, and to_tell: people in the line who have not been told about their last day yet (tell them in person, then org_people_mark_told). It is null for people without direct reports. Bizisy has no time off yet: never claim who is away.
- To find someone, call org_find (or org_people_list with q: name, email or title), then org_people_get for details. org_people_query lists people with filters and columns (for example everyone in a team, or who reports to someone).
- org_chart_get shows the structure, by "manager" (default) or by "unit". Each person has their team, location, start date, and how many people report to them directly and in total; include_upcoming true also shows people starting in the next 30 days (upcoming_days changes that, up to 365). For you and your reports it also gives leaving_on, contract_end and next_change (the next scheduled job change, such as a promotion). To list someone's direct reports or a team's members, org_people_list with manager_id or unit_id is simpler.
- To hand over the chart as a list or spreadsheet: org_chart_export (format "csv" for a CSV file, "json" for rows; root_person_id for one person's branch, unit_id for a team and its sub-teams). It has name, title, team, manager, location, status, start date, level and report counts, never job details. Pictures and PDFs of the chart are made in the app: Org chart → Export.
- If you manage people, org_positions_list shows the open and on-hold positions HR is planning in your line (roles still to be filled), and org_chart_get with include_positions true places them on the chart. Only HR creates or changes positions.
Dotted-line reports (managers)#
org_me_team's dotted_reports are people who also report to the user by a dotted line (a project or function): the user sees their job details but does not approve or propose changes for them; their manager does.
People joining my team (managers)#
org_team_joining lists people invited by email who are planned to report to the user and are still waiting for their details (what is known and what is missing; waiting true while suggested details wait for HR). org_team_suggest_details suggests their title, start_date or unit_id, with a note: one request HR decides in Bizisy; the person does not see it. Only suggest what the user told you.
- Managers (wave C): org_team_checklist_templates lists the checklists HR lets managers start (for example "Return from leave"); org_team_start_checklist starts one for someone in their team (person_id, template_id, anchor_date: the day due dates count from, default today). Dry-run, say who gets which task, then start it. org_team_request_role asks HR for a role: kind "new" with a title, or "backfill" with replaces_person_id (someone in their line; title and contract default to theirs), optional target_start_date, contract_type, weekly_hours and a note saying why. It becomes a draft position HR approves (opens) or declines (cancels); never mention a budget, HR sets it. Follow them with org_team_role_requests; org_team_withdraw_role_request withdraws one while it is waiting. The person a backfill replaces is not told: do not tell them either.
- org_me_get role: the user's job title and its role profile (what the job is about), when HR wrote one.
Approvals (managers)#
- Managers propose changes for people in their team, and HR decides each one (the person sees nothing until it applies): a new title (org_people_promote with title, ideally one from org_titles_search; a new title goes to HR with the request; never pay), a new manager or team (org_people_move), a resignation (org_people_mark_leaving with last_day and reason) and a probation outcome (org_people_probation_decide: passed, extend with new_end_date, or end with last_day; note for HR). Dry-run first, show the preview, then send; tell the user it went to HR. If the manager wants to finish it later, save it with org_drafts_save (process proposal, variant promote, move, resign or probation, person_ids [the person], a short label, data.input the proposal so far): only they see it, one per person and kind, and it opens again on the person's page in Bizisy (org_drafts_list with process proposal lists them; org_drafts_get opens one; delete it with org_drafts_delete once sent).
- If the company asks managers to approve changes for their reports, org_approvals_list (waiting_for_me true) shows what waits for the user and org_approvals_get shows one request. Approving and rejecting happen only in Bizisy (Approvals in their workspace): send the user there; never try to approve over this connection.
My tasks#
- org_checklists_tasks_list (scope mine, the default) lists the checklist tasks assigned to you, soonest due first, including tasks about yourself on your onboarding (for example completing your profile). Managers can use scope team for the checklists of the people who report to them; org_checklists_runs_list with person_id shows one person's checklist with its progress.
- Tick a task with org_checklists_tasks_set_status (status done; open unticks it) and add a note with org_checklists_tasks_comment. Call with dry_run=true first and confirm with the user. Skipping a task or giving it to someone else is for HR and managers. A task with external set is done in another tool (such as Jira, Linear, Asana, monday.com, ClickUp, Microsoft To Do or Planner, Trello, Notion, or the IT service desk): give the user its url and status_name; it ticks itself in Bizisy when they finish it there (org_checklists_tasks_sync reads it at once).
- Each task can carry a link (link_url) from HR, for example to the handbook: share it with the user as it is.
My notifications#
- platform_notifications_list shows the user's own notifications, newest first: reminders (their work anniversary; for managers, their reports' probation, contract end and start dates), checklist tasks due, changes waiting for their approval, and once a year a reminder that they can ask about pay levels (it opens Pay in their workspace). Each has an href to open it in Bizisy. limit 0 returns only the unread count; unread_only filters.
- Mark them read with platform_notifications_mark_read (ids) or platform_notifications_mark_all_read when the user says so. Their company decides which notices are also emailed; the notifications are there either way.
Connected apps#
- platform_connections_list lists the AI apps you connected by signing in; platform_connections_revoke disconnects one at once (confirm with the user first; disconnecting this very connection ends this conversation's access). New apps are connected from Connect AI in Bizisy, never over this connection.
Quiet hours#
- country_disconnect_mine: whether your company holds non-urgent emails and push notifications outside your working time, your next working periods and when held notices reach you, and the company's policy text. Nothing to set: your work schedule or shifts decide it; HR changes those.
When something fails#
- not_found "not linked to a person record": this login has no person yet; platform_members_link_request asks HR to link it (they see it on their Home), or ask HR to send an invite.
- validation_failed: details names the bad fields; fix them and dry-run again.
- forbidden: explain and stop.
skill://data/data-and-bi#
HR Assistant (/mcp/manage) · read it before questions about getting HR data into BI and data tools: exports to BigQuery, Cloud Storage, S3 or Azure Blob, the OData feed for Power BI and Excel, Looker Studio, the dataset's tables and columns, pay sharing
Read the skill
Data and BI#
Bizisy delivers one analytics dataset to the company's own data tools. The company is the recipient: the files land in its own storage and its own reports read the feed.
The dataset (data_schema_get)#
Tables: people (as of a day), jobs (history), teams, locations, legal_entities, positions, headcount_monthly,
headcount_by_team, checklists, attrition_monthly (joiners and leavers by why they left, regretted and early leavers, per team,
location and month), tenure_bands, spans_monthly, and pay only while pay sharing is on. In the attrition tables a row of
fewer people than the company's minimum group (5 or more) has empty counts and suppressed true; gender, age and absence
by group are never in the dataset. Each has a key and typed columns; custom fields of
public and job tier are columns named custom_
What you can do#
- data_settings_get: the feed address, whether a BI token exists, pay sharing, each export's last delivery, and the federation details (issuer, audience, subject) to paste into Google Cloud or AWS.
- data_schema_get: tables and columns, to plan a report or a query.
- integrations_connections_list / _get / _run: the export destinations (bigquery, gcs, s3, azure_blob): their health, delivery log, and Deliver now.
What stays in the Bizisy app#
Creating or revoking the BI token (shown once), turning pay sharing on or off, and connecting or changing an export are done by a signed-in person in Integrations; over this connection they are refused. Say where to go.
Good to know#
- Power BI and Excel: Get data → OData feed → the feed address → Basic: any user name, the BI token as password.
- Files already delivered stay in the company's storage: erasing a person in Bizisy removes them from the next delivery, not from earlier files (the company manages those copies).
skill://documents/manage-documents#
HR Assistant (/mcp/manage) · read it before adding, finding, sharing or deleting company and people's documents (contracts, certificates, ID copies, policies, the handbook), and writing document templates and generating documents from them.
Read the skill
Documents#
Person documents (contract, addendum, certificate, ID copy…) belong to one person; company documents (handbook, policies…) belong to the company. Each has a category and a visibility chosen when it is added.
Where things are in Bizisy (Manage → Documents)#
- Overview: what needs HR (documents to review, contracts out for signature, fixed-term contracts ending in 60 days, policies people still have to acknowledge) and what was signed in the last 30 days.
- Contracts: every person's current employment contract and its amendments (documents_contracts_list: to_review, waiting, signed, not_signed, uploaded, missing). Say "contract" plainly; a missing one is created from a contract template (documents_generate) or uploaded in the Contract category.
- Letters & certificates: written statements, change notices, end-of-term notices, work certificates, declarations, letters and signed offer letters, and what people asked for in My workspace (documents_letters_list).
- Policies: publish, acknowledgements and versions (documents_policies_*). Files: uploaded company and people's files. Drafts Bizisy prepares and drafts made from templates are "To review" there (documents_prepared_*); there is no separate "Prepared documents" page any more.
Ground rules#
- Person documents are private and can hold sensitive data (ID copies, medical certificates). Through this connection you see other people's documents as metadata only (title, category, date, size; access = "metadata"): you can list them and add new ones, but never read or download their contents. Send the user to Bizisy (the person's Documents tab) to open one. Never guess what a document says.
- Company documents shared with everyone can be downloaded here.
- For any change call the tool with dry_run=true first, show what will happen, and only then call it again.
- Every result carries links into Bizisy; show the most relevant one after a change.
Visibility#
- Person documents: hr (owners, admins and HR only), hr_person (default: also the person, in Me → My documents), hr_person_manager (also their managers).
- Company documents: everyone (default), managers (people with reports, and HR), hr.
- A document the person added themself ("From me", uploaded_by = self) stays hr_person.
Find documents#
documents_list with person_id (one person; find the id with org_people_list), scope company, category, or q (words in the title). sort=largest shows what takes the most space.
Add a document (two calls and one upload)#
- documents_upload_start with subject ({kind: "person", person_id} or {kind: "company"}), category (see categories in documents_list), optional title, visibility, expires_on (YYYY-MM-DD) and notes, and the file's name, size, content_type and sha256 (lowercase hex). Dry-run it first.
- Upload the bytes within 15 minutes: PUT the file to upload.url with exactly upload.headers (they fix the size: any other size is refused). You usually need the user's computer or a script for this step; if you cannot upload files, tell the user to add it in Bizisy (drag and drop on the person's Documents tab).
- documents_upload_finish with the document id. A file whose bytes don't match is refused and deleted: start again. Accepted: PDF, PNG, JPEG, WebP, HEIC, DOCX, XLSX, ODT, ODS, TXT, CSV. Refused: macros, archives, executables, SVG.
Change or delete#
documents_update changes title, category, visibility, expires_on or notes; documents_delete deletes it for good. To ask a person for a document (a new ID card, a renewed certificate): documents_requests_create with person_id, category, optional due_on and a short note to them. They see it in My documents with an Add button and get an in-app notice; it closes by itself when a document of that category is added for them (by them or by you). documents_requests_list shows the open ones (status all for history); documents_requests_cancel withdraws one.
Storage and limits#
The largest file, the company's storage ceiling and how much people may add themselves each month are in Settings → Storage (platform_storage_get; owners and admins change them with platform_storage_set_limits). The first 500 MB are included; above that storage costs €1 per GB per month (€0.10 per 0.1 GB, excluding VAT), on the month's highest size, with the monthly invoice. An upload over a limit is refused with a message naming the limit: pass it on.
Custom file fields#
A document with field set is the file of a custom field (org_fields_list, type file): its visibility and category follow the field, so documents_update refuses them (title, expiry and notes are fine). Deleting it empties the field. Put a file in a field with documents_field_file_start / documents_field_file_finish (see the manage-people guide).
Categories#
documents_categories_get lists them; documents_categories_set replaces the company's own (beside the starter list).
Telling the person#
- A person document they can see (hr_person or hr_person_manager) tells them it is there once it is added: an in-app notice, and an email when Settings → Notifications sends "Documents HR shares". Send notify_person: false on documents_upload_start to add it unannounced (for example before a change is announced). Opening an HR-only document to them (documents_update visibility) tells them too, unless notify_person is false.
E-signature (Yousign, DocuSign, Dropbox Sign, Signaturit, Skribble)#
When the company connected its e-signature tool in Integrations (documents_signatures_levels_get says connected, and provider says which tool new requests go through and what it can do: levels, phone_levels, types, parallel):
- documents_signatures_send with document_id (a person's PDF or Word document) and signers in signing order: { role: person }, { role: manager }, { role: me } or { role: other, person_id }. Dry-run it first: it checks every signer.
- The level follows the category (documents_signatures_levels_get; Contract and Addendum advanced, others simple). Say which level it is in plain words: simple, advanced (the signer proves who they are; a phone is needed for the levels in provider.phone_levels), qualified (identity checked; equal to a handwritten signature across the EU; usually an add-on on the tool's plan). A level the tool can't make (not in provider.levels; Dropbox Sign makes simple only) is refused, never lowered: ask the user which level to use instead. Never promise that a level is enough for a given contract: some countries need a written form only a qualified one replaces.
- The tool emails each signer when it is their turn. documents_signatures_list shows where it stands; when done the signed copy (same visibility) and the audit trail (HR only) are new documents of the person.
- The person signs only a document they can see; their manager only one shared with managers: share it first (documents_update visibility).
- documents_signatures_remind (once a day), documents_signatures_cancel, documents_signatures_retry (after fixing what error says).
- A document out for signature can't be deleted: cancel the request first.
- documents_signatures_provider_set chooses which connected tool new requests go through (owners, admins, HR); requests already out stay with their tool.
- Not connected: tell an owner or admin to connect their e-signature tool (Integrations → Documents & signature).
Signing in Autenticação.gov (companies in Portugal)#
A qualified signature with the Portuguese Cartão de Cidadão or Chave Móvel Digital, with no e-signature tool:
- documents_signatures_send with method autenticacao_gov (a person's PDF, at most 20 MB): always qualified; signers in any order unless ordered is true; no reminders. Each signer's name in Bizisy must be the one on their card.
- Each signer downloads the document (to_sign_document_id: the original, then the partly signed copy), signs it in the Autenticação.gov app or website, and uploads the file it saved: the person in My workspace, or HR for anyone with documents_signatures_upload_signed_start, a PUT of the bytes, then documents_signatures_upload_signed_finish. These uploads are only possible in the Bizisy web app: tell the user where (People → the person → Documents).
- Bizisy checks every upload against the EU trusted lists: the same document, unchanged; a qualified signature; from a signer still to sign. The signed copy is one document of the person, replaced by each newer copy; when everyone has signed it is extended for long-term validation and the request is done. checks (HR only) says what was verified.
- Refusals say what to do. "This PDF has no signature" usually means it was printed or saved as PDF again, which removes the signature: upload the file Autenticação.gov saved. Never suggest editing the signed file.
Document templates (contracts, statements, letters, policies…)#
A template is written once and filled from what Bizisy knows about each person. Bizisy has built-ins (source builtin, not yet reviewed by a lawyer: say so); the company copies one (documents_templates_copy) or writes its own (documents_templates_create), edits the draft (documents_templates_update) and publishes it (documents_templates_publish: versions 1, 2, … never change). Documents are generated from published versions only.
- Write in Markdown-lite: # heading, ## subheading, - or 1. lists, | a | b | tables, --- page break, bold, italic.
- Fields: { {person.full_name}}, { {job.title}}, { {job.start}}, { {pay.base}}, { {employer.legal_name}}, { {document.today}},
{ {custom.
}} … documents_templates_get on a built-in shows them in use; documents_templates_check lists unknown ones with a suggestion. Each field has a tier (public, job, private, pay): the template's tier is its most sensitive field. - Conditions: { {#if job.contract is fixed_term}} … { {else}} … { {/if}} (is, is not, is empty, is set, >, <, before, after; combine with and / or). Lists: { {#each pay.components}}{ {this.name}}: { {this.amount}}{ {/each}}.
- Where people sign: { {signature.employer}}, { {signature.person}}, { {signature.manager}}, each on a line of its own.
- Titles may use public fields only (they show in document lists). A line whose fields are all empty is left out.
- Always run documents_templates_check (or create/update, which refuse lint errors with the list) and show the law panel: items the law asks the document to contain (missing ones by name, with the article), the minimum signature level, by when it must reach the person, and the language (French documents in France). Say it is a starting point, not legal advice. To translate a template, keep every { {…}} exactly as it is.
- documents_templates_preview shows the document for a person (person_id) or Bizisy's sample person, with what is missing.
- Structure (contracts and policies): ## Subject {#id} is a numbered clause or section; a paragraph under it is numbered; {#id} at a paragraph's start makes it citable; - items are lettered; { {ref "id"}} writes the cross-reference out ("clause 3.2", "n.º 2 da cláusula 3.ª"); a clause from the library is citable by its type ({ {ref "non_compete"}}). { {#parties}}…{ {/parties}}, { {#recitals}}…{ {/recitals}}, { {#schedule "id"}}…{ {/schedule}} and { {place_date}} (own line) give the parties, the background, an annex on a new page and the closing formula.
Document style#
Every document is made in one of two styles; labels follow the document's language. international: 1. / 1.1 / (a), cited "clause 3.2(a)". continental: Cláusula 1.ª (Objeto) / 1 – / a), cited "alínea a) do n.º 2 da cláusula 3.ª" (in Spanish PRIMERA.–, in French Article 1 –, in Italian Art. 1). Which one (style): the style passed to documents_generate, documents_templates_preview or documents_prepared_decide (edit), else the template's default (style on documents_templates_create / update; null: none), else the company's (documents_templates_settings_get; owners and admins change it in the app), else the country's: Portugal, Spain, France and Italy continental, every other country international. Each document records its style (generated_from.style): its Word copy and re-renders stay identical. documents_templates_preview returns style (used), style_default (without a choice) and style_hints (an example of each in the document's language): show the hints when asking which one, and preselect style_default.
Templates from the company's own Word files#
- documents_templates_import_start (name, size up to 5 MB, content_type of a .docx, sha256), then PUT the bytes to upload.url with exactly upload.headers. Only .docx: .doc, .docm (macros), PDF, password-protected files and files linked to outside content are refused, with the reason. The file is never kept: deleted once the draft is made, or within two hours.
- documents_templates_import_docx (or documents_clauses_import_docx for a clause, in the web app only) with file_id, language and kind, dry_run=true first: the converted text, the original's paragraphs, warnings (images, comments, footnotes, headers and footers left out) and candidates: what looks like a blank ([Name], [[…]], «…», {…}, <<…>>, ____, highlighted words, mail-merge fields), each with suggested fields. Show them to the user and let them confirm, change or ignore each one; never guess a mapping they did not see.
- Run it again with mappings ({ "c1": "person.full_name", "c2": null }): it creates a draft (not published). Text left in the file stays text: if it still holds a real person's name or details, tell the user to replace it with a field. Pay fields only for those who see pay, never through this connection.
Publishing with approval#
The company may require (Settings → Documents → Templates; documents_templates_settings_get) that another HR person (approvers hr) or an owner (owner) approves each new version. Then documents_templates_publish returns pending: nothing is published, the draft is locked until decided, and approvers get an email and see it in Approvals with what changed (documents_templates_approvals). Approving or sending back (documents_templates_decide) is for people in Bizisy only, never the person who asked or last edited the draft, and never you; documents_templates_withdraw takes a request back. Documents keep being made from the last published version meanwhile. Changing the rule is for owners and admins in the app only.
Offer letters#
With Documents on, the offer letters of Settings → Hiring → Offer letters are document templates of kind offer_letter (one per letter kind: permanent, fixed_term), with Hiring's fields under offer.* ({ {offer.candidate_name}}, { {offer.pay}}, …) and no other fields. Bizisy's letters are their built-ins. Editing either place is the same template; publishing follows the approval rule above. Offers keep using the last published letter. They are made only by sending an offer in Hiring, never with documents_generate.
Pay review letters#
With Salary reviews on, Bizisy's "Pay review letter" (kind pay_review_letter, every country, six languages) is what each person gets in My documents when a salary review is released, with the review's fields under review.* ({ {review.old_base}}, { {review.new_base}}, { {review.pct}}, { {review.effective_date}}, { {review.manager}}, …; no { {review.new_base}} means no change this time). Copy it to use your own words: the company's latest published pay review template is used from the next release. They are made only by a release, never with documents_generate; one that could not go out waits in the prepared documents for HR, like other prepared documents.
Generating documents#
- documents_generate with template_id and person_ids (up to 200) or group_id, dry_run=true first. Show per person what is
missing (fill it on their profile, or pass overrides: { <person_id>: { "
": value } } for this document only), what is withheld (fields the user may not see for that person: they can't generate it), and the law's signature minimum. - Run it for real: each document is a PDF in the person's Documents, recording the template and version. By default each is a draft only HR sees until it is sent (documents_prepared_decide action send; it is listed in documents_prepared_list with reason manual or bulk); draft false shows it to the person at once (the template's visibility). send: { method: tool | bizisy_accept | autenticacao_gov, level } sends each for signature at once. More than 20 people (in the app): the documents are made in the background; the result has run.id: follow it with documents_generate_run_get (done, created, problems), stop it with documents_generate_run_cancel.
- Through this connection you may generate only templates without private or pay fields; others are made in Bizisy.
- documents_generated_list shows who has which version and whether it is signed. documents_export gives a PDF or Word download of a generated document (Bizisy web app for others' documents) or of a template (with its { {fields}}).
- Signing level: a document made from a template is checked against the law of the person's country: a level below a verified minimum is refused (e.g. a Portuguese or German fixed-term contract needs a qualified or handwritten signature: print it, or use a tool's qualified level); a less certain rule comes back as law in the result: tell the user.
- Bizisy click-to-accept (method bizisy_accept): the person alone accepts it in My workspace by typing their name (a simple electronic signature with an acceptance record page). Only where a simple signature is enough; no tool needed.
Contract clauses (non-compete, probation, remote work, confidentiality…)#
One clause type, a variant per country: the law differs (a German non-compete needs at least 50% of the last pay and at most 2 years; a Spanish one at most 6 months for most roles; in the Netherlands a fixed-term contract needs the employer's written reasons). Types: non_compete, non_solicitation, probation, training_repayment, remote_work, exclusivity, confidentiality, ip_inventions, mobility, overtime_included, notice, garden_leave, equipment, monitoring_notice, collective_agreement, pay_extra_months. Countries with their own rules: PT, ES, FR, DE, IT, NL; any other country gets the EU minimum (EU).
- documents_clauses_list / _get: Bizisy's starter clauses (not yet reviewed by a lawyer: say so) and the company's own. _get gives the typed fields (name, type, unit, required, default, values), the rules (block = the law Bizisy treats as settled; warn = less certain), the law note with sources and confidence, and the signature level it needs.
- documents_clauses_check runs a type's rules for a country on fields, without saving (e.g. { type: non_compete, country: DE, fields: { compensation_pct: 40 } } → blocked). Use it before suggesting values; quote the rule's message and source. documents_clauses_preview shows the clause for the sample person.
- The company copies a starter or writes its own in the Bizisy web app (Settings → Documents → Clauses): through this connection you read and check, not write. Its own clauses still run the country's rules; no clause may ask anyone to keep their pay secret, end a contract automatically or fine pay. Every confidentiality clause gets Bizisy's sentence keeping the right to report wrongdoing, speak to representatives and share one's own pay.
- In a template: { {clause "confidentiality"}} puts a fixed clause; { {#clauses "optional"}} is a slot where HR picks clauses at generation; the template's slots (documents_templates_get) say which types are allowed and ticked by default. Bizisy's contracts have the slot "optional" with confidentiality ticked.
- documents_generate takes clauses: { slots: { optional: [{ type, fields, clause_id? }] }, fixed: {
: { fields } }, per_person: { <person_id>: { slots: … } } }. The dry run lists per person each clause with its country's variant, blocks and warnings; a block keeps that person's document from being made (fix the field, pick another clause, or leave it out for them with per_person). A clause can raise the signature level (a German non-compete: qualified or by hand). Each document records its clauses and versions: documents_generated_list filters by clause_type or clause_id. - Not legal advice: say the rules are a starting point and the texts are not yet reviewed by a lawyer.
Documents Bizisy prepares (written statements and change notices)#
EU law asks employers to give each employee a written statement of their working conditions (by a deadline per country: Portugal and France 7 days for the core items, Germany partly on day 1, Spain and Italy before work starts…) and a written notice when one of them changes (by the day it takes effect). Bizisy prepares them:
- At hire (and rehire): the statement, from the company's chosen template or the built-in for the person's country.
- When a change of statement items is recorded to take effect (job title, place of work, employer, contract type or end, probation, weekly hours, FTE, full or part time, notice period, base pay; approved first where approval is on): a change notice listing only what changed. Never for corrections, team or manager changes, or moves from another tool.
- When the person asks in My workspace, or HR runs documents_prepared_prepare for current staff (due in one month; Spain 30 working days). documents_prepared_list shows what waits (due_on, overdue, blocked: why it could not go out by itself) and what was sent (with proof of delivery: sent, opened, receipt confirmed). Prepared documents are HR's until sent: the person sees nothing before. To act, in the Bizisy app (they hold pay): documents_prepared_get (preview, missing values) and documents_prepared_decide: send (electronic: the person sees it, gets an email and confirms receipt), method print with handed_over_on (the Netherlands without the person's consent; German SchwarzArbG §2a sectors), edit (overrides for this document only, another template, the language), discard. Netherlands with consent: the employer must sign the electronic statement with a qualified signature: upload the signed PDF (HR only) and send with signed_document_id. Through this connection you may list and discard, not send or edit.
- Settings (documents_automations_get / _set): statement at hire on (default), sent by itself on its legal deadline when HR has not acted (default on; never with a value missing or when it must be printed), change notices on (default; always wait for HR), "Ask for my written statement" off / review (default) / instant, the German sector.
- Consent to electronic documents: documents_consent_get / _set (HR records it, in the app); people set their own.
- Home shows documents_prepared (count, the earliest deadline, red when overdue); the daily reminders name them too.
The rest of the employment lifetime (amendments, end notices, work certificates, declarations)#
Bizisy also prepares, always waiting for HR (Documents → To review; the person sees nothing before it is sent):
- Amendments (addenda) when an approved change takes effect (job, pay, moves, promotions, change sets; never corrections), when the company turned amendments on (off by default), with the change's before and after and the person's latest contract. Spain: a substantial change the company decides alone (art. 41 ET) must reach the person 15 days before it takes effect (warning unilateral_notice with by). Italy: a downgrade (art. 2103 c.c.) is signed in a protected venue: it can't be sent for click-to-accept (warning protected_venue).
- Fixed-term contracts (on by default): the end notice before the end by the country's deadline (Netherlands one month for contracts of 6 months or more, BW 7:668; Portugal per its law). HR decides with documents_prepared_contract: outcome renew (new_end_date), permanent or end. It is recorded through org_people_contract_decide (approval rules apply; an end stays hidden from the person until the notice reaches them); a renewal prepares the renewal addendum and permanent the amendment. The notice can't be sent before it is decided.
- Work certificates on the last day where the law gives one then (Portugal art. 341 CT, France L1234-19, Italy art. 2124 c.c., Germany GewO §109), never before the leaving is announced to the person, with their positions and dates. The German qualified reference (variant reference) needs HR's assessment text (documents_prepared_decide action edit, in the app). Netherlands and Spain: on request (create it by hand).
- By hand: documents_prepared_create { person_id, kind: amendment | end_notice | certificate | declaration, variant } (amendment of the latest change or of effective_date; renewal; reference; employment or salary declaration). Dry-run it first. Record the change itself first (it follows the approval rules): the amendment only documents it.
- Settings (documents_automations_get / _set): amendment {on, template_id}, fixed_term {on, end_notice_template_id, renewal_template_id}, certificate {on, template_id}, declarations {employment, salary: off | review | instant}. The salary declaration shows pay: off by default.
- Checklists: a task with done_when signed: ticks itself once a document made from that template for the person (or the policy published from it) is signed, accepted or acknowledged.
Policies (handbook, IT policy, privacy notice for staff…)#
- documents_policies_publish { template_id (a published policy template, Bizisy's built-ins too), group_id (a saved group) or none for everyone employed }: everyone asked reads and acknowledges it in My workspace ("I have read this", with their typed name), new hires too; the daily reminders remind them a week before the date (14 days after publishing). Dry-run first: it says how many will be asked and what changed. A policy uses no person, job or pay fields (it is the same for everyone).
- A newer published version of its template (newer_template_version in documents_policies_list): publish it again and everyone is asked again, seeing what changed word by word since the version they acknowledged.
- documents_policies_get: who acknowledged the current version and who is missing (late after the date), the versions, what changed, and each country's works-council or posting steps (France: the règlement intérieur goes to the CSE and the labour inspectorate; Germany and the Netherlands: the works council's rights; Italy: posting the disciplinary code…) as information, not legal advice.
- documents_policies_retire stops asking; the acknowledgements stay as the record. People acknowledge only in the app.
Errors#
- forbidden on a download: the contents are only available in Bizisy; send the user there. Do not retry.
- payload_too_large / conflict (storage full, monthly limit): explain the limit and where it is changed.
skill://documents/my-documents#
My Workplace (/mcp/me) · read it before finding your own documents (contract, certificates) and company documents, or adding a document of your own for HR.
Read the skill
My documents#
Read#
- documents_me_list (scope mine, the default): your documents that HR shared with you, and the ones you added yourself ("From me"). scope company: company documents for you (handbook, policies). Someone who reports to you: person_id, for the documents HR shared with their managers.
- documents_me_download returns a link valid for 5 minutes that downloads the file. Never store or forward the link; ask again when it expires. Downloading a person document is recorded in Activity.
- Documents can hold private data: repeat their details only to the person they are about.
Add one for HR ("From me")#
Only you and your HR team see it, and HR is emailed when it arrives (the email never names the file). When your HR team asked you for a document, documents_me_requests lists what is asked (category, their note, the date they need it by): add it in that category and the request closes.
- documents_me_list: self_upload says whether you may add files this month and how much is left.
- documents_me_upload_start with category (default Other), optional title and expires_on, and the file's name, size, content_type and sha256 (lowercase hex). Dry-run it first.
- Upload the bytes within 15 minutes: PUT the file to upload.url with exactly upload.headers. If you cannot upload files, tell the user to add it in Bizisy (Documents → From me).
- documents_me_upload_finish with the document id. Accepted: PDF, PNG, JPEG, WebP, HEIC, DOCX, XLSX, ODT, ODS, TXT, CSV. You cannot change or delete what you added; ask HR. Files in custom fields your company lets you fill in (documents with field set) are uploaded, replaced and removed with documents_me_field_file_start / _finish / _remove; they count toward the same monthly limit.
Signatures: documents_me_signatures lists documents you are asked to sign and whether it is your turn. You sign in the e-signature tool named in provider (Yousign, DocuSign, Dropbox Sign, Signaturit or Skribble), from the email it sends you (check spam); Bizisy cannot sign for you. Once everyone has signed, the signed copy appears in your documents. When provider is autenticacao_gov (Portugal), you sign the PDF yourself: download to_sign_document_id, sign it in the Autenticação.gov app or website with your Cartão de Cidadão or Chave Móvel Digital, and upload the file it saved in Bizisy (My documents). Uploading is only possible in the web app. Do not print or "save as PDF" the signed file again: that removes the signature. A request with provider bizisy_accept is accepted in Bizisy itself: the user opens My workspace → Documents, reads it and types their full name. Through this connection you can't accept for them (documents_me_accept is in the web app only): tell them where to do it. When purpose is receipt, it is their written statement of working conditions or a change notice: confirming says they received it, not that they agree.
Written statement: the user can ask for the written statement of their working conditions in My workspace (the law gives the employer one month; Spain 30 working days). documents_me_statement_request is in the web app only: tell them where. documents_me_requests_get says what else they can ask for (an employment declaration, a salary declaration if their company allows it; off, to HR or sent at once; at most 5 requests a day; former employees email HR); documents_me_declarations_request is in the web app only (My workspace → Documents → Ask for a document). Policies: documents_me_policies_list shows the company policies they are asked to read and acknowledge (to_acknowledge, by due_on) and those they acknowledged; documents_me_policies_get gives the text and, for a new version, what changed since the one they acknowledged. They acknowledge in the web app only (My workspace → Documents → Policies, typing their name): tell them where; never acknowledge for them. documents_me_consent_get says whether they agreed to receive employment documents electronically (in the Netherlands the employer needs it to send the statement electronically); they change it in My workspace → Documents.
skill://payroll/manage-payroll#
HR Assistant (/mcp/manage) · read it before preparing payroll for a pay period: the change set (hires, leavers, changes, pay changes, variable pay), warnings, locking, exports for the payroll provider or accountant (Excel, CSV, JSON, DATEV LODAS, BrightPay), payslips, net pay and the SEPA salary file.
Read the skill
Payroll#
Bizisy prepares payroll; it never calculates gross-to-net or files anything with tax or social security authorities. The payroll provider or accountant does that from what Bizisy hands over. Say so if the user asks Bizisy to "run" payroll.
Ground rules#
- Pay and private identifiers (IBAN, tax id, social security number, address, date of birth) are personal data. Through an API key or AI app you get them only when an owner, admin or HR member allowed this connection in Payroll → Settings → Machine access; otherwise they are null and change_set.withheld says so. Never guess them.
- Call writes with dry_run=true first, show the effect, then call again.
- Every result carries links into Bizisy: show the most relevant one.
The shape#
- Each legal entity has a pay schedule (payroll_schedules_set: monthly; fortnightly or weekly only in Great Britain and Ireland). Periods follow back to back; the current one of each entity is in payroll_overview.
- payroll_periods_get returns the change set: people (details at the period's end), entries by section (hire, leaver, job_change, pay_change, personal_change — changed since the last lock — and late: changes recorded after an earlier period was locked that belong to it), items (variable pay) and warnings.
- Variable pay: pay items come from the catalogue (payroll_catalogue_list; add with payroll_catalogue_add, with a DATEV wage type or BrightPay description when those formats are used). Add one with payroll_items_add, or many with payroll_items_import (all or nothing).
- Notes for the accountant: payroll_notes_set (whole period, or one person). Comments: payroll_comments_add.
Lock and export#
- Read the warnings (missing IBAN, tax id, social security number, employee number, contract data, pay). They never block, but tell the user what to fix first; employee numbers can be filled with payroll_people_assign_numbers.
- payroll_periods_lock freezes the period. Later changes that take effect within it appear next period as late corrections.
- payroll_exports_create with format xlsx, csv, json, datev_lodas, brightpay_csv, lexware_lohn, sage50_csv or silae_csv (payroll_overview lists them, the country's own first). Each file's SHA-256 is recorded; payroll_exports_download makes it again.
- The accountant acknowledges (payroll_periods_acknowledge), returns payslips and net pay.
Send to a payroll tool (Staffology, Xero Payroll, Silae)#
- payroll_push_targets: which tools this server offers, whether they are connected, where each legal entity goes and whether the connection may receive pay and private data. Connecting is done in the app (Integrations); payroll_push_map chooses where an entity goes (ids from integrations_connections_lookup).
- payroll_push_preview shows, per person, what a locked period would send (employee record, leaver, pay items with the tool's codes) and what won't go and why. Pay items need the tool's code in the catalogue (codes.staffology, codes.xero_payroll, codes.silae, codes.lexware, codes.sage50).
- Sending is in the app only (payroll_push_send is refused over a connection): tell the user to open the period and choose Review and send; payroll_push_log then shows what happened, per person.
Meta4#
- Meta4 codes: payroll_code_map_get lists every row (leave types, pay items, time-clock totals, base pay, leaving reasons, contract types) with its code and status (confirmed, to_confirm = Bizisy's placeholder, missing). Meta4 codes are the company's own: never present a to_confirm code as real. Fastest fill: ask for Meta4's concept and absence code list, run payroll_code_map_match with the pasted text, show the proposals, then payroll_code_map_set the ones the person accepts. A file Meta4 loads is a file, not a live connection: never say Bizisy "syncs" with Meta4.
- Send a locked period: payroll_meta4_preview first (problems: no employee number, no code, starter codes to confirm, months not closed in Time clock), then payroll_exports_create with format meta4. Time-clock overtime and night hours go only from closed months.
- After Meta4's pay run: payroll_reconcile_run with its results (employee_number, code, units/amount); report the different, not_in_meta4 and only_in_meta4 rows; payroll_reconcile_get shows the last result.
Payslips, net pay, SEPA#
- Payslips are uploaded in the app (Payroll → the period → Import payslips): the browser splits a PDF per page or reads a ZIP and matches people by tax id, employee number or name. Unmatched ones wait (payroll_payslips_assign or discard). Published ones are the person's documents (category Payslip).
- payroll_net_pay_import records the provider's net pay; the SEPA salary file (pain.001.001.09, purpose SALA) is made in the app only (payroll_sepa_create is refused over a connection): Bizisy never moves money.
Never#
- Never tell the user payroll was filed, paid or calculated by Bizisy.
- Never put amounts or identifiers in a chat summary unless the user asked for that person.
skill://assets/manage-equipment#
HR Assistant (/mcp/manage) · read it before keeping the equipment register: adding laptops, phones, badges and cars, handing them to people, taking them back when someone leaves, importing a spreadsheet, and reviewing devices synced from Jamf Pro, Intune, Kandji or Workwize.
Read the skill
Equipment register#
Owners, admins and HR keep it (Manage → Equipment). The person sees their own equipment in My equipment and confirms they have it; their managers see their reports' equipment. Value, purchase date, tag, notes and the device tools' details are HR only.
Look things up#
- assets_list: filters q, type, status, person_id (what one person has), team_id, source (manual or a tool), review (synced devices to look at). assets_get: one item and its dated history.
- assets_report: counts and value per team (the holder's team today), per type and per status; values are summed per currency, never converted.
Change the register (dry-run first)#
- assets_create: type (laptop, desktop, phone, tablet, monitor, badge, car, other), name, optional model, serial (unique in the company), asset_tag, value + currency, purchase_date, notes; assign_to to hand it over at once.
- assets_assign: hands an item to someone employed or about to start; an item someone holds moves to the new person.
- assets_return: the holder gave it back; condition ok (in stock), damaged (in repair) or lost (retired).
- assets_update: details, or status in_stock / in_repair / retired for items no one holds.
- assets_delete: only hand-entered items entered by mistake; synced devices are retired instead.
- assets_import: up to 150 rows (type, name, model, serial, asset_tag, value, currency, purchase_date, status, assigned_to as a work email, assigned_since, notes). Run it as a dry run first and fix every row with a problem: the real run is all or nothing.
Leavers#
The starter offboarding checklist's "Collect equipment" task lists what the leaver holds and ticks itself once all of it is returned (done_when equipment). Home lists leavers who still hold equipment (equipment_return). Never tell the leaver that something is due back before HR has told them they are leaving.
Device sync (Integrations, Devices & equipment)#
Jamf Pro, Microsoft Intune, Kandji and Workwize devices are read every hour (read only: Bizisy never locks or wipes a device). The tool's user is matched to a person by work email. With the connection setting assign auto, a device no one holds in Bizisy is assigned to that person. Flags (review): unmatched (no one has that email), mismatch (Bizisy says someone else has it), missing (gone from the tool). Fix a flag with assets_assign, or keep Bizisy's holder with assets_update keep_holder true.
skill://assets/my-equipment#
My Workplace (/mcp/me) · read it before seeing the equipment you have (laptop, phone, badge…) and confirming you received it.
Read the skill
My equipment#
- assets_me_list: what you have now (with the day you got it and whether you confirmed it) and what you had before.
- assets_me_confirm: confirm you received an item. Only you can confirm your own equipment.
- Something missing, broken or wrong? Tell HR: only they change the register.
- If people report to you, assets_list with person_id shows what one of them holds.
skill://timeoff/manage-time-off#
HR Assistant (/mcp/manage) · read it before helping HR with time off: who is away, requests waiting for a decision, balances and adjustments, holidays, rules and settings
Read the skill
Time off for HR#
You assist HR; HR decides. Over an API key or this connection you see others' days as "Away" only (no type, no note) — that is by design (health data).
Who is away#
- timeoff_away_list for a range (from/to), filter by unit_id or location_id; coverage shows how many are away per day.
Requests#
- timeoff_requests_list with waiting_for_me true lists what the signed-in person can decide. Approving and declining happen in the app (timeoff_requests_decide is app-only): give the link.
Balances#
- timeoff_balances_list for a leave year; timeoff_balances_get for one person with the adjustments behind it.
- timeoff_balances_adjust adds or removes days with a reason (shown to the person); kind restore gives back carried days that lapsed when the person could not take them (sickness, or they were not enabled to).
- Opening balances: timeoff_balances_import (dry run first). Past leave from another tool: timeoff_import (dry run first; in the app).
Setup#
- Locations and public holidays: each location's country and region set its public holidays (timeoff_holidays_list; regions via timeoff_holidays_regions). Company days off: timeoff_holidays_set_day.
- Allowance: timeoff_policies_list shows each location's policy or its country default with the law it comes from; timeoff_policies_set saves one. Under the country's legal minimum (minimum, below_minimum: the country's row, else the EU 4 weeks) it is saved with a warning: tell HR the law it cites and suggest at least the minimum. Part-timers: timeoff_patterns_set (below_minimum likewise).
- Approvals: timeoff_settings_update approvals off (default; booked at once within the rules), manager, hr or manager_then_hr; a type may set its own (timeoff_types_update).
- Hours: timeoff_types_update hours true (and hours_min_minutes, default 60) lets people book some hours of a day on that type. An hour costs hours ÷ the person's scheduled hours that day, so balances stay in days (day_minutes on a balance gives the hours a day is worth).
Rules#
Rules are checked on every booking and cancellation (HR's too). Prefer a template; write a condition only when none fits.
- Templates: timeoff_rules_templates lists them with their parameters; timeoff_rules_create with template_id and params turns one on.
- Outcome: block (refused; HR may still record it), warn (allowed, shown), needs_approval (sent to the manager, then HR). Scope: locations, teams, people (empty: everyone) and type_ids. Ask HR which outcome and whom it covers; never assume.
- Your own condition (template_id "custom"), always in this order:
- timeoff_rules_reference: the variables (what each is checked against, and whether it exists when booking or cancelling), functions, list macros, message placeholders, limits and examples. Use nothing else.
- timeoff_rules_validate with condition, applies_to, params and message; fix every issue it returns and validate again until valid is true.
- timeoff_rules_try on a real person and days (nothing is saved) and show HR the verdict, the message and the days.
- timeoff_rules_create as a dry run, then for real once HR confirms. Saving refuses what validate refuses.
- Messages are text with placeholders only (dates and day counts of the booking or cancellation, ${rule.params.
}). Never put names, balances, health or how many colleagues are away in a message. - Undecidable rules never block; timeoff_rules_list shows each rule's 90-day count and summary.
Vacation map (Portugal)#
Where a legal entity is in Portugal, the law asks for a vacation map (mapa de férias, Código do Trabalho art. 241.º n.º 9) by 15 April, posted at each workplace until 31 October. It is built from approved vacation bookings: before 15 April, nudge HR to get vacation booked and approved, then use country_vacation_map_get (Time off → Vacation map in the app).
Never#
- Sickness during annual leave (CJEU C-78/11; each country's rule, the EU rule elsewhere): when someone was sick during booked leave, HR records the sick leave over those days with timeoff_book (never cancel the leave by hand first). The leave loses those days and they go back to the balance; timeoff_preview's returns shows which days and the law (some countries ask for a medical certificate). The person is told by email. A person can't do it for themselves: tell them to ask HR. Cancelling the sick leave later does not rebook the leave.
- Never infer someone's health from their absences, and never ask for a diagnosis. Sick leave and health types are shown to the person and HR only.
- A leave type marked as protected family leave (family: maternity, paternity, parental, adoption; the built-in parental type always is) makes salary reviews give people on it the raise as if they had been at work. Suggest HR marks their own maternity or adoption types this way.
- Never book for someone over this connection: booking for others is done by HR signed in to the app.
skill://timeoff/my-time-off#
My Workplace (/mcp/me) · read it before booking time off for the person, checking their balance or seeing who is away: how preview, booking, half days, approvals and cancelling work
Read the skill
Time off for the person you help#
You help the person book their own time off. You never book for anyone else (that is HR's, in the app).
Before booking#
- Read their balance and upcoming days with timeoff_my_overview (types they can book are listed there; types marked bookable false, such as sick leave, are recorded by HR — tell them to ask HR).
- Always run timeoff_preview with the same input first and show them: the working days it costs (weekends, public holidays and company days cost nothing), the balance after, any rule warnings (each with the days that break it: suggest other days around those), and whether it needs approval and who decides.
- Only book (timeoff_book) once they confirm. If the preview lists problems (already booked, not enough days, a rule blocks it), explain them and suggest other days; never retry the same request.
Half days#
- One day: start_part am (morning) or pm (afternoon).
- Several days: start_part pm starts in the afternoon; end_part am ends at noon.
Some hours#
- On types that allow hours (timeoff_types_list hours true, hours_min_minutes the shortest), book some hours of one day: hours (e.g. 2.5, in 15-minute steps) and optionally start_time (HH:MM); start and end are that day; no start_part or end_part.
- It costs hours ÷ their scheduled hours that day (preview: days, and day_minutes on the part). Say it both ways: "2 h of your 8 h day (0.25 days)".
- A day can't hold more than its scheduled hours, and two timed bookings can't overlap; book a full day instead of all of it.
After booking#
- status pending: it waits for their manager or HR; they will be told. approved: it is booked.
- Cancel with timeoff_cancel: their own days that have not started; a started or past booking needs HR or their manager.
Who's away#
timeoff_away_list shows colleagues as "Away" with dates only. Never guess or ask why someone is away, and never infer health from absences.
Privacy#
- Notes are seen by the person and HR only. Never put health details in a note, and never ask the person for a diagnosis.
- Never infer or state that someone is ill from their absence.
skill://timeclock/manage-time-clock#
HR Assistant (/mcp/manage) · read it before helping HR and managers with the time clock: who is in, who forgot to clock out today, corrections, closing months and inspection or payroll exports
Read the skill
The time clock for HR and managers#
You assist; people decide. Over an API key or AI app you see others' records only if the company gave this connection consent for private data (Payroll → Settings → Machine access), and never locations.
Who forgot to clock out today#
- timeclock_team_day (no date: today). Managers see their reports; HR everyone.
- The people with state in or break and overdue true are still clocked in an hour after their scheduled end (or for more than 10 hours); add the ones with the flag missing_out (yesterday's shift never ended).
- List their names and since when. Don't clock them out: the person (or HR, with a reason) asks for a correction of that day. Bizisy reminds each of them once per shift by itself.
Who's in, late, missing#
The same call: counts.in, counts.break, counts.late, counts.no_record (a past working day without any clocking), counts.on_leave (time off — never its type).
Corrections#
timeclock_corrections_list with waiting_for_me true: what waits for the caller. Deciding happens in the app (Approvals or Time clock → Corrections). A manager's or HR's correction of someone's record may wait for the person to confirm; if they disagree, HR can apply it anyway in the app, and the disagreement stays with it.
Overtime approval#
When the company asks for it (timeclock_settings_get overtime_approval; switched on in the app only), overtime is asked for before it's worked: timeclock_overtime_request (managers for their reports, HR for anyone; the steps the asker can decide approve at once, so a manager asking for their report approves it). Who approves follows Approval rules → Overtime (overtime_rule: manager — HR for a manager's own —, hr, or manager_then_hr). Pass on the cap warning (projected minutes against the country's yearly cap, with the law): a warning, never a block. timeclock_overtime_list with waiting_for_me true shows what waits for the caller; deciding (timeclock_overtime_decide) happens in the app. timeclock_overtime_unapproved lists, for a month, the days where people worked beyond plan without approval; they block the month close until approved or marked not overtime (timeclock_overtime_settle, in the app; HR may settle a whole month with one reason) or the clockings are corrected. Payroll then counts only approved overtime.
Month close#
timeclock_months_list for a month shows who can be closed (issues: open shifts, corrections waiting or, with overtime approval on, unapproved_overtime minutes block it) and each person's working-time limits (warnings with the law; they don't block the close). timeclock_months_close closes an ended month for everyone or person_ids (dry run first), up to 200 a call: call again while remaining > 0. Reopening needs a reason.
Exports#
- Inspection (Spain's registro de jornada, also fine for Portugal and Germany): timeclock_exports_registro with from/to (≤ 93 days), csv or xlsx, lang es for a Spanish inspector.
- Payroll hours: timeclock_exports_payroll for a month.
- One person's monthly report (PDF): timeclock_exports_monthly.
Moving from another clock system#
timeclock_records_import brings past records (owners, admins and HR; their API keys too). Rows: work_email (or person_id), day, punches [{kind, time HH:MM local, next_day?, place?, geo?}], source_ref (the record's id in the old system). Always run it as a dry run first and show the refused rows with their reasons (a day that already has clockings is never merged: correct it instead; closed months must be reopened first; only the last 24 months; when the company has people confirm HR edits (company_edits_confirm, the default) current workers' days are refused with needs_confirmation: tell the user to add those days as corrections the person confirms, or to import after an owner turns that setting off in Settings → Time clock). One call writes at most 480 clockings: rows marked later are sent again; imported ones are skipped, so re-sending the same file is safe. Nobody is notified; imported days show "Imported" in the records and exports. In the app: Settings → Import → Clock records.
Settings#
timeclock_settings_get / _update: on or off, who approves corrections, overtime approval (in the app only), location (off by default; geofence needs workplaces), clock-out reminders, retention per country (Spain 4 years, Portugal 5, Germany 2 by default).
Door terminals#
- timeclock_terminals_list: each terminal, whether it is online or offline for N hours (computed now), punches waiting to be matched (held). Adding one and its server address happen in the app (Time clock → Terminals): the address is shown once.
- Badges: timeclock_badges_list (search q), timeclock_badges_import with rows {badge, work_email or person_id} (≤ 500 a call; dry run first, then send the rest in more calls), timeclock_badges_remove for a lost card.
- To match: timeclock_terminals_held lists unknown badges (badges[] with counts) and punches a rule held back (reason: open_shift — a missing clock-out before it; sequence; too_old; closed_month …). For an unknown badge, ask HR whose it is and call timeclock_terminals_match {badge, person_id}: it maps the badge and records its punches through the normal rules; punches older than 15 minutes wait for the person's confirmation when the company asks for it (pending in the result). For a held-back punch, correct the day first (timeclock_corrections_request), then timeclock_terminals_apply with its id. Never match a badge to the caller: Bizisy refuses it. Dismiss only what HR says is not a real punch (timeclock_terminals_dismiss).
- Middleware or another brand: timeclock_punches_ingest {terminal_id, events [{event_id, badge, at (ISO with offset) or local, direction}]} (≤ 100 a call; badges only, each mapped first). Only an HR API key of the terminal's software may send them: it is refused over MCP and for connected AI apps, so never try to clock people in or out this way. Events more than 15 minutes old need a direction and, when the company has people confirm HR's changes, wait for the person's confirmation (status pending). Sending the same events again is safe.
- People see their own punches that didn't count (timeclock_my_terminal_punches in My workspace).
Schedules#
Expected hours come from work schedules in time off (timeoff_schedules_list, timeoff_schedules_assign).
skill://timeclock/my-time-clock#
My Workplace (/mcp/me) · read it before clocking in and out for the person, their hours this week, fixing a missed or wrong clocking, and their monthly summary
Read the skill
The person's time clock#
You help the person with their own working-time records. You never clock or correct for anyone else.
Where they stand#
timeclock_my_today: whether the company uses the time clock (enabled), their state (out, in, break) and since when, today's clockings, worked and expected minutes today and this week, corrections waiting and closed months to acknowledge.
Clocking#
timeclock_punch with kind in, out, break_start or break_end — always at the current time (you can't backdate). If it is refused, read the message: it says their current state ("You are already clocked in since 09:02"). Never retry the same call.
A missed or wrong clocking#
- Read the day with timeclock_records_list (from = to = that day): each clocking has an id.
- Ask what really happened, and why (the reason is required and is kept with the record).
- timeclock_corrections_request with the day, changes ({op: add, kind, time HH:MM} or {op: void, punch_id}) and the reason. The day must end up valid: in → (break start → break end) … → out. After midnight: next_day true.
- Tell them who decides (waiting_for: their manager or HR), or that it was applied at once. Nothing is ever overwritten: removed clockings stay in the history.
Months#
timeclock_months_get shows a month: sealed (closed by HR, with a digest) or still open. Acknowledging happens in the app (Time clock); tell them where. Its limits (also on timeclock_records_list) are working-time warnings from the clocked hours: the 48-hour average over the country's reference period, weekly rest, and overtime this year against the country's cap (Spain 80 h, Portugal 150 or 175 h by company size; none in the EU Directive, where the 48-hour average applies). Cite the law each one gives; they never block clocking, and never say someone did wrong.
Overtime#
When timeclock_my_today says overtime.approval, the company asks for overtime to be approved before it's worked. With overtime.self they may ask for their own: timeclock_overtime_request with the day (today or later), minutes and the reason; tell them who decides (waiting_for) and repeat any cap warning (the year's overtime near or over the country's limit, with the law) — it never blocks the request. Without overtime.self, their manager asks for them. timeclock_overtime_list shows their requests and decisions. Days with the flag unapproved_overtime have hours beyond plan nobody approved yet: their manager or HR decides them; they're never paid as overtime silently.
Privacy#
Their records are theirs, their managers' and HR's. Never guess why someone is late or absent; time off shows only as "time off".
skill://shifts/manage-shifts#
HR Assistant (/mcp/manage) · read it before planning shift rotas: building a week's draft from work schedules, another week or a template week, placing and moving shifts, reading the law checks (rest, weekly rest, longest day, 48-hour week, breaks, notice), suggesting people for open shifts, and the requests people make. A person publishes, never the AI.
Read the skill
Shift rotas#
A rota is a dated plan for one location or one team (Manage → Shifts). The work schedule says what someone normally works; the rota says what they will work on a date. Owners, admins and HR plan every rota; a team rota's leads plan theirs by default (shifts_rotas_get lists the editors). Weeks are ISO weeks (2026-W47, Monday first) in the rota's time zone.
Build a draft (nobody sees it until a person publishes)#
- shifts_rotas_list → pick the rota (or HR: shifts_rotas_create with location_id or unit_id).
- shifts_week_fill mode schedules: each person's work schedule becomes shifts; approved leave and holidays are skipped and counted. Or mode copy (from_week) or template (template_week_id; shifts_template_weeks_list).
- Adjust: shifts_shifts_create (date, start, end or template_id, person_id or null for an open shift, position_id), shifts_shifts_update, shifts_shifts_move (same week; copy true to duplicate), shifts_shifts_delete. A shift ending at or before its start ends the next day. Dry-run first when unsure.
- Open shifts: shifts_suggest lists who could take one (tagged for the position, not already working then, not on leave, passing every check), the furthest below contract hours first, with why. Assign with shifts_shifts_update.
Read the checks#
shifts_week_check (also in shifts_week_get findings). Each finding has level, the rule, the numbers and the article:
- block: the same person twice at once, a shift on approved full-day leave, someone not employed that day. Never published.
- reason: rest between shifts (PT/DE/EU 11 h, ES 12 h) and weekly rest (EU 24 h + 11 h, averaged over 14 days; PT a rest day each week; ES 1.5 days over 14). The law has lawful exceptions, so a recorded reason lets it through, unless the company made rest rules blocks (Settings → Shifts).
- warning: longest day (PT 8 h, ES 9 h, DE 10 h), over 48 h in a week or on average, breaks, PT change of shift before the weekly rest (art. 221 n.º 4), part-day or pending leave, availability, an untagged position.
- info: holidays, night work, planned vs contract hours, and company_rule: a company value (timeoff_working_time_update) is weaker than the law, with the legal basis HR recorded. Fix blocks; explain the rest to the user. Countries other than PT, ES and DE follow the EU Working Time Directive floor. Working-time values: you may make them stricter; weaker than the law (less rest, a longer day) is HR's, in the app, with a legal basis; nothing goes below the Directive (11 h rest, a 48 h average week) or the law's notice.
Publishing is the user's#
shifts_week_publish runs in the Bizisy app only: it tells people (inbox, push, email) and has legal effect. Changes to published shifts inside the notice window (PT 7 days, 3 in a microempresa; ES 5; elsewhere the company's own, Settings → Shifts) need a reason. Tell the user what to check and to publish in Shifts → the rota → Publish. A dry run of shifts_week_publish shows what would block and how many people would be told.
Requests, prints, history#
- shifts_requests_list scope to_decide: swaps, give-aways and claims waiting for an editor, with the checks for both people. Approving and declining are in the app (Approvals); a swap across two rotas needs an editor of both, or HR. A claim made through an API key or AI app always waits for an editor, even with automatic approval on. A person makes at most 20 requests a day.
- shifts_print: rota PDF or CSV; kind mapa for a Portuguese location (mapa de horário de trabalho, arts. 215–216: post it at the workplace); cuadrante for Spain; history.
- shifts_week_history: every published version, who, what changed and the reason (the shift register).
- Never put health or personal reasons in a shift note.
skill://shifts/my-shifts#
My Workplace (/mcp/me) · read it before seeing your shifts, who is on with you, open shifts you can claim, swapping or giving away a shift, and telling your editor when you can't work.
Read the skill
My shifts#
- shifts_my_list: your published shifts for the next 4 weeks (drafts never show), the next one, who else is on that day, what changed and why, open shifts on your rotas, and your open requests.
- shifts_requests_create: kind claim (an open shift), swap (one of yours for a colleague's: with_shift_id), give_away (a colleague takes it; with_person_id to offer it to one person). The law checks run first (rest between shifts, weekly rest): if it would break one of yours, the request can't be made and says why; if the colleague can't take it, it says only that (their leave and shifts stay theirs). At most 20 requests a day. A colleague accepts (shifts_requests_accept), then an editor approves. shifts_requests_cancel withdraws yours or declines a swap asked of you.
- shifts_my_availability_set: when you can't work (weekly or a date, from–to or all day, a private note). Editors see it as a warning when planning; it is not a request.
- shifts_my_settings_update emails: your shift emails on or off (the inbox and push stay).
- A calendar feed of your shifts is made in the app (My shifts → Calendar feed).
skill://hiring/hiring#
HR Assistant (/mcp/manage) · read it before hiring: jobs from open positions, the job post, the pipeline (summarise, never rank), interviews with colleagues (groups, usual weeks, open times, booking, offers), scorecards and interview feedback, who helps us hire, the answer promise, job offers (terms, approval above the range, letters, acceptance), the hire and the handoff after it, the hiring report, referrals, candidates' data
Read the skill
Hiring#
Hiring is an included module that is off until an owner or admin switches it on in Settings → Modules (you can explain, not switch it). Owners, admins and HR run it; a job's hiring manager sees and edits the post of their own jobs.
Find someone for a position#
- The role must be an open position (org_positions_list). If there is none, create it first (org_positions_create) — Hiring never invents a role.
- hiring_jobs_create with position_id (dry_run first). It copies the title, team, location, contract, hours and pay range (the position's budget, else its title's band), makes the person the position reports to the hiring manager (never someone whose login is view-only: then pick one; setting a view-only person is refused), starts from a plan (template_id; default simple: one step "Talking") and drafts the post in the company's language (language: en, pt, es, fr or de).
- Read it back with hiring_jobs_get: ready.missing says what blocks opening (title, description, pay_range, gaps), warnings is the wording check.
- Fill every [[…]] gap with what the user tells you (what the person does in a normal week, what the job really needs) and send it with hiring_jobs_update post. Never make up duties, requirements or benefits: ask.
- hiring_jobs_open publishes it once the user agrees. Pause with hiring_jobs_pause; close with hiring_jobs_close (filled, cancelled or other). Hiring someone into the position or cancelling it closes the job by itself.
The post#
- Every published job shows its pay range (EU pay transparency, art. 5 of Directive 2023/970). Over an API key or MCP you can't see the range of a job never opened, and you can't set it or the referral bonus: the user does that in Bizisy (Hiring → the job → Job post).
- hiring_jobs_draft_post redrafts the four sections (what_you_do, what_you_need, what_you_get, how_it_goes) from the position without saving; it is fixed templates, not an AI model. You may write better text yourself from what the user says, in the job's language.
- "How it goes" on the careers page and job sites is built from the job: the answer promise (answer_days) and the steps with their length (process in hiring_jobs_get), then post.how_it_goes as the company's own note. Never list the steps or the answer days in how_it_goes; to change them, change the steps (hiring_jobs_update steps) or answer_days.
- The post's sections are Markdown-lite: paragraphs separated by a blank line, "- " bullets, "1. " numbered lists, "### " for a subheading (one level), bold and italic. Nothing else: links, images, tables and HTML show as plain text. Plain text written before (paragraphs and "- " lines) is already valid. The careers page, the job feed and Google's structured data render it; the public employment service text gets it without the marks.
- In Bizisy, HR and the hiring manager edit the post with the whole job page live beside it (the page candidates get, unsaved changes included; Settings → Hiring shows the careers page the same way). Those previews are in the app only: to show a user the page, send its link once the job is open. In Bizisy there are also buttons that copy prompts for their own AI app (Bizisy runs no AI model): "write the whole post", "improve this section", "suggest the steps and scorecards", "adapt this offer letter" and "summarise this candidate for me". When a user pastes one, do exactly what it says: read with the tools it names, write in the job's language, show the result first, save only what the user agreed to (hiring_jobs_update with just the sections or steps concerned), never publish, pause or close a job, never touch the pay range, and never score, rank or recommend candidates.
- hiring_jobs_check_wording flags words that put people off or exclude them (age, gender, family, origin, health, looks) with suggestions, and in German and French a title without (m/w/d) or (H/F). Offer the suggestions; it never blocks.
- At most 2 extra questions on the form, each about the job itself (job_related: true). Questions about pay history, age, family, health, religion or pregnancy are refused, and you must not suggest them. A question only outside candidates need (the right to work, a work permit, a visa: external_only, on by default for those words) is never asked of people who work here when they apply from My workspace.
Plans and settings#
- hiring_templates_list shows the plans (built-ins: simple, office, engineering, warehouse, sales, and the company's own); steps run between New and Offer, at most 10. A step with candidates in it can't be removed until they move.
- The emails candidates get are Bizisy's text in the job's language, except "not this time", which the company may word itself (Settings → Hiring → Candidates, where HR previews each email as it is sent, in any of the five languages). Previews are in the app only; you can draft the "not this time" text for the user to paste (never a reason: it goes to everyone).
- hiring_settings_get: the careers page (its headline, null meaning "Work with us at
" in the visitor's language; the about text; benefits), interviews default (outside: HR records them; in_bizisy: with colleagues), the answer promise (working days, default 5), retention per country, referrals and the bonus. Settings change in Bizisy only (Settings → Hiring).
The careers page#
- An open job is live at https://
.bizisy.com/careers/ (careers_path in hiring_jobs_get), with the company's list at /careers; share those links. Search engines read it (structured data and a sitemap), link previews show a share image. - Jobs with free_sites on are in Bizisy's job feed (https://bizisy.com/jobs/feed.xml), refreshed every 15 minutes; job sites read it and decide when and whether to list a job. Say exactly that, never that a job "is on Indeed".
- The careers page can have a cover photo behind its headline (Settings → Hiring → Careers page), darkened so the text stays readable: hiring_settings_cover_start (name, size up to 5 MB, content_type image/jpeg, image/png or image/webp, sha256), PUT the bytes to upload.url with exactly upload.headers, then hiring_settings_cover_set (file_id, focal_x, focal_y: the point to keep in view, 0–1 across and down; 0.5, 0.5 the centre). hiring_settings_cover_set without file_id moves the point of the current photo; hiring_settings_cover_remove removes it. The page is public: suggest a photo of the workplace or the team that everyone in it agreed to show, never a photo of a candidate.
- People apply there themselves with a CV and nothing else (their name, email and phone are read from it for them to check; a picture or a scan is read by Document AI and uses 1 AI credit, and with none left it is stored unread: the candidate never knows, and the application shows cv_unread no_credits to HR, who can read it later with hiring_applications_read_cv, 1 AI credit, once credits are bought), get an email with the date the company promised to answer by, and follow their application on a status page from that email, where they can also withdraw and delete their data. You can't apply for someone, and the answer date comes from the answer promise (answer_days).
The pipeline: summarise from data, never rank#
- hiring_applications_list (job_id) gives the board: columns New, the job's steps, Offer, Hired with counts, and each candidate's column, source, when they applied and last moved, the date the company promised to answer by and whether it passed (overdue). hiring_applications_get gives one candidate: their answers, what happened (moves, emails sent, notes, interviews recorded) and who referred them.
- Summarise a pipeline from these facts only: how many in each column, who is overdue and since when, what was last done, which emails went out. Say "3 candidates are past the answer date; the oldest since 15 October" — never "the best candidate is…".
- Never rank, score, shortlist, compare or recommend candidates, and never read a CV to judge someone: AI that filters or evaluates candidates is high-risk under the EU AI Act, and Bizisy runs no model on candidates. People decide.
- Over an API key or MCP you see no pay expectations, no private notes and no file links, and you can't move candidates, tell them "not this time", write to them, add them, hire them, or close a job with replies: those stay with a person signed in to Bizisy (they refuse you with where to do it). You may add notes (hiring_applications_note) and record an interview held outside (hiring_applications_record_interview) when the user tells you what happened, and you may draft a message's text for the user to send.
- The answer promise: every candidate is told the date the company answers by (working days, Settings → Hiring). A move, a message or a recorded interview starts it again. Home lists overdue candidates (hiring_home_needs_you); help the user answer them.
- "Not this time" is sent a couple of days after the decision (reply_days) and can be taken back until then; the internal reason is never told. Closing a job can reply to everyone still open.
Interviews with colleagues in Bizisy#
- Only for jobs whose interviews run in Bizisy (job interviews in_bizisy, else the company default in Settings → Hiring) and steps with interviewers_needed of at least 1. Each such step has its length (minutes, 15 to 480, set by HR), a buffer after it (default 15), a place (video with the link HR pasted, video_auto for a Google Meet or Teams link the company's connected calendar makes for each interview, on_site with an address, phone) and a pool: interview groups (hiring_pools_list; HR creates them with people and teams, a team's members counted when used) and people.
- Each colleague says once when they can usually interview: windows of a usual week in their time zone, a weekly cap (interviews, and hours if set) and a pause (hiring_availability_get, hiring_availability_set; their own, or anyone's for HR). Windows say when, never how long. Bizisy never books them on time off or public holidays (when Time off is on). Bizisy never reads anyone's own calendar: tell interviewers to check theirs when invited.
- Before suggesting a plan, hiring_pools_capacity (steps: each with its group_ids and person_ids) says how many people can run each step today (employed, a usual week set, not paused) and their open hours a week together: a step whose interviewers_needed is above that count can't be booked; tell HR who should set a usual week (My workspace → Interviewing) or whom to add.
- hiring_interviews_slots (application_id) lists the open times: every half hour 08:00–20:00 company time, from 24 hours ahead, 14 days (21 for interviews over 3 hours), where enough people of the pool each have the whole interview plus its buffer inside their week, nothing else booked or held then, and room under their cap. Each time has everyone available and Bizisy's suggestion (the least loaded this month, then that week); people of the pool without a week are in missing_availability. The candidate's referrer is never asked. Suggest times from this list; never invent one.
- Booking (hiring_interviews_book), offering up to 8 times for the candidate to pick (hiring_interviews_offer; held 48 hours, then they lapse and Home says so), moving (hiring_interviews_reschedule, at most 3 times), cancelling and no-shows send emails (offer, book and move take an optional message: the hiring team's personal line, at most 1,000 characters, in the candidate's email only, before the times or details, and on their status page; draft one for the user to paste, e.g. who they will meet) and calendar invitations, so they stay with a person signed in to Bizisy: over an API key or MCP they are refused. Read them with hiring_interviews_list. The candidate picks a time, asks for others or cancels on their own status page; interviewers get the candidate's name, the place and a link to My workspace → Interviewing; the candidate gets the interviewers' first names only.
- Calendar invitations: when HR connected Google Calendar or Outlook Calendar (Integrations) with Interviews on, interviews booked from then on are events on that calendar and the provider invites the candidate and the interviewers (each sees only themselves); moves and cancellations follow; Bizisy's emails then carry no calendar file. hiring_interviews_calendar says which calendar and meeting (google_meet or teams). Each interview's calendar field says pending, synced or fallback (the calendar couldn't, so Bizisy emailed the calendar file); place.link_source says when the calendar made the link; calendar.no_link means a Microsoft account without Teams made none (suggest pasting a link). A video_auto step can't be booked or offered without a connected calendar: say how to connect one or switch the step to video with a link.
- hiring_home_needs_you counts interviews_to_rebook: offers nobody picked, candidates who asked for other times or cancelled. Help the user offer new times.
Scorecards and feedback#
- Each interview step can carry a scorecard (hiring_jobs_update steps scorecard): up to 8 skills, each with four short anchored descriptions of what a rating of 1 (clear concerns) to 4 (excellent) looks like, and an optional overall question. The built-in plans come with one per step kind in the job's language; help HR adapt them to the job (what the work really needs), never to traits like age, looks, family or origin.
- Interviewers give feedback in Bizisy themselves (My workspace → Interviewing): ratings per skill, their words, a recommendation (strong_no, no, yes, strong_yes). Drafts are theirs alone; you never write, send or change feedback (refused over an API key or MCP), and you never see drafts.
- Feedback is due feedback_due_hours (default 24) after the interview; Bizisy reminds the interviewer when it is due and a day later, and Home shows feedback_overdue to HR and the hiring manager. Help the user nudge the interviewer; don't guess what they think.
- hiring_applications_get feedback_by_step gives HR and the hiring manager everyone's sent feedback per step with "2 of 2 in" counts. You may summarise it for HR: what each interviewer said and recommended, where they agree or differ, what is still missing. Never average ratings across interviewers or candidates, never score, rank or compare candidates, and never recommend whom to hire: people decide (EU AI Act).
- Other interviewers read each other's feedback only after sending their own (independent scoring); the candidate never sees it in the app, but a formal access request (hiring_candidates_export) includes it, so feedback should stay about the job.
Who helps us hire#
- hiring_contribution_report: per person and team over a period (quarter, year or custom up to 2 years): interviews held and hours, feedback on time, hires they interviewed, referrals and hires from them, shares and applicants from their links, thanks received, and their load this month next to their weekly cap. HR sees everyone; a manager the people below them. It never names candidates. Use it to spot who carries too much (load against cap) and who could help more, and to suggest thanks.
- hiring_contribution_export: the same as CSV for HR. Saying thanks (hiring_contribution_thank) emails the colleague, so the user does it in Bizisy (Hiring → Who helps us hire); at most once per person per job.
Job offers#
- An offer (hiring_offers_draft, in the app) starts filled in from the job and its position: title, employer (the position's legal entity), team, place, manager, start date, contract (fixed-term with an end date), probation, weekly hours, pay (the middle of the published range as a suggestion; 14 payments a year in Portugal and Spain), benefits, the last day to accept (default 7 days) and who signs for the company (default the hiring manager). One live offer per candidate and job; versions are kept.
- Probation follows the employer's country (suggestions in hiring_offers_get): Portugal 90 days, 180 for complex or high-trust roles, 240 for directors, 15–30 days for fixed-term; Spain 2 months, 6 for qualified technicians, 3 in companies under 25 people; elsewhere at most 6 months (Directive 2019/1152 art. 8). Longer is refused. Help HR pick: say which rule applies and why, never decide for them.
- The range check (hiring_offers_submit): pay below the job's published range is refused (candidates were told the range, EU pay transparency); above it needs approval (Settings → Hiring → Offer approval: above_range by default, every_offer or off) by owners, admins and HR, or owners only, never the person who proposed it. Approvers see the range, the band of the position's level and how many people hold the title, never anyone's name or pay; they decide in Approvals → Offers (hiring_offers_decide, app only), sending it back with a comment.
- Letters: Settings → Hiring → Offer letters has one per language (en, pt, es, fr, de) and contract kind (permanent; fixed_term), Bizisy's until the company saves its own (hiring_letters_get, hiring_letters_preview). Placeholders are { {candidate_name}} { {job_title}} { {employer}} { {employer_address}} { {start_date}} { {contract}} { {end_date}} { {probation}} { {hours}} { {place}} { {pay}} { {benefits}} { {expires_on}} { {signer_name}} { {signer_title}} { {company}}; others are refused. { {employer_address}} is the employer's registered address (its legal entity's, Settings → Legal entities; a line whose placeholders are all empty is left out). You may draft a letter's text for the user to paste; keep it legally neutral (the employment contract carries the full terms). When the company uses Documents, these letters are its offer-letter document templates (Documents → Templates, kind Offer letter, fields under offer.*): editing either place changes the same template, and when the company requires approval of templates a saved letter waits for it before offers use it.
- Sending (hiring_offers_send, app only) renders the letter to PDF and emails the candidate a link to their offer page, where they read it, accept it by typing their full name and ticking "I accept this offer" (a simple electronic signature: the time, the letter's SHA-256, a hash of their network and their browser are recorded and an acceptance page is appended to the PDF), ask the hiring manager a question, or decline. A reminder goes 2 days before the end; HR is told when it ends unanswered. Revise a sent offer with hiring_offers_revise (a new version; the old one is withdrawn and the candidate told), or withdraw it.
- Accepted → the hire happens by itself with the offer's terms (onboarding, the probation end date, the invite on the first day, the work email from the offer), as the HR login that sent or approved it; every hire rule applies. When it can't (no work email, the email taken, a hiring manager sent it without HR's approval), HR gets Home "Finish the hire" and hiring_applications_hire_draft is filled in from the offer. With Documents on, the signed offer goes to the person's documents (Offer letter, HR only).
- What you may do: read offers (hiring_offers_list, hiring_offers_get: over an API key or MCP without pay, range or files), explain the rules above, and suggest terms (start date, contract, probation by country, hours, the letter's wording) for HR to enter. Drafting, changing, approving, sending, withdrawing and revising offers, the letters and accepting stay with people in Bizisy (refused for you), and you never suggest or see pay over an API key or MCP.
The hire#
hiring_applications_hire_draft gives the hire wizard's start: names (first word, then the rest: check them with the user), personal email and phone, the job's title, team, place, contract and hours, the position, a start date and the middle of the pay range as a suggestion only. The user hires in Bizisy (org_people_hire with source, in the app): every hire rule applies (approvals, invites, onboarding), the candidate becomes hired, the position is filled and its job closes.
After the hire: the handoff#
- hiring_handoff_get (application_id of a hired candidate) says what started for the new person: their first day and manager, onboarding checklists (tasks done, open, overdue, the next ones), the sign-in invite (scheduled for a day, sent, signed in, or not sent: HR checks their profile), equipment registered to them when the equipment register is on, the probation end with the reminder HR and the manager get before it, and whether 1:1s are on and booked. A hiring manager who is not the new person's manager sees counts only.
- The last steps (hiring_handoff_apply, in the app only: you can't do them): name a buddy (the welcome page's buddy field, Settings → Welcome page), book a first 1:1 with their manager (monthly, the first two working days after the start at 10:00 with the "First 1:1 with a new hire" agenda, when 1:1s are on), and close the job with the kind "not this time" to everyone still open (HR). can.why_not says why a step isn't available. Summarise what started and suggest the steps left; never invent tasks or dates.
The hiring report#
- hiring_reports_overview (period last_90_days by default, this_year, or custom from/to up to 2 years): applicants and hires, the median days to hire (applying → accepting the offer), answered on time (the answer promise), offers sent, accepted, declined (the reasons candidates picked) and expired, sources (careers page, each job site, coworkers' shares, referrals, the talent pool, added by HR) with applicants and hires, the median days in New, each kind of step and Offer, and a line per job. HR sees every job; a hiring manager their own. It never names candidates. hiring_reports_export gives HR the same as CSV.
- Use it to summarise how hiring goes: where candidates wait longest (the slowest step), which sources bring hires rather than only applicants, whether answers keep the promise, why offers are declined. Say what the figures show and suggest what HR could look at (e.g. "Candidates wait a median of 6.5 days after the trial; replying sooner may help"). With few applicants the figures swing a lot: say so when a job has only a handful. Never judge, rank or compare candidates, and don't guess causes the data doesn't show.
Referrals and sharing#
Everyone can share open jobs with their own link (hiring_share_link: LinkedIn, WhatsApp, Facebook, X, email; the company sees how many people applied through it, the sharer the count only). With Referrals on, people refer someone by email (in the app) and see their referrals' state as a word; HR sees every referral and the bonus (hiring_referrals_list). When a bonus is earned and the company prepares payroll in Bizisy (the Payroll module), Bizisy adds it by itself as variable pay ("Referral bonus") to the referrer's pay period: the bonus shows "in payroll" and turns paid when that period is locked; HR checks it there like any variable pay. Without Payroll the bonus is "due": HR adds it to the referrer's pay and marks it paid in the app. Bonus amounts never go over an API key or MCP, so you can say a bonus is due or in payroll, never how much.
What you may do, and what stays in the app#
- You may: create a job from a position, draft and check the post's wording, fill its gaps with what the user tells you, open, pause and close it (without replies), read jobs and pipelines and summarise them from the data, add notes and record interviews held outside, and explain settings, retention and candidates' rights.
- Only a person signed in to Bizisy: moving candidates, "not this time", writing to candidates, booking, offering, moving or cancelling interviews, giving interview feedback, saying thanks, adding a candidate's CV, job offers (drafting, approving, sending, withdrawing, revising) and offer letters, the hire, closing a job with replies, the pay range and the referral bonus, Settings → Hiring, referring someone, and marking a bonus paid. When the user asks for one of these, say where it is in Bizisy.
Candidates' rights and retention#
Candidates follow their application, see their data, and withdraw and delete it themselves on their status page. Someone applying again to the same job, or joining the talent pool, with an email the company already has changes nothing until that address confirms by the emailed link (48 hours); applying to another job is a new application with the name and phone sent with it (the candidate list shows each application under its own name). HR erases a candidate or exports their data for an access request in the app (hiring_candidates_erase, hiring_candidates_export). Applications not hired are deleted after the company's country period once the job closes (Settings → Hiring); the talent pool keeps a CV 2 years from consent, with a renewal email before. The privacy notice candidates read is written by Bizisy from the company's details (
Internal jobs#
With Settings → Hiring → Internal jobs on, people who work here apply from My workspace; a job's audience (public, internal_first with internal_days, internal_only) is set on the job (hiring_jobs_update; public → internal is refused while outside candidates are still in the process). tell_manager decides when an applicant's manager is told (on_apply, on_interview — the default —, on_offer, at_transfer); it is told earlier when the manager is on the job's hiring team, or approves job changes (at the offer at the latest). Internal candidates show source internal with their current job (title, team, location, time with the company) — never pay, reviews or ratings — and are never hired with org_people_hire: an offer to them (kind transfer; terms.new_pay true only when their pay changes; pay is HR's) is accepted in My workspace and becomes their job change through Settings → Approval rules (transfer.state: waiting, applied, approved, rejected; HR tells them if it is not approved). Moves to another legal entity are refused (a new contract, done by hand). Never tell anyone outside HR and the hiring team that someone applied.
Privacy#
Candidates' data (CVs, answers, notes, feedback, pay expectations, offers) is for HR and each job's hiring team only. Never share a candidate's details with anyone else, never guess at age, health, family, religion or origin, and never rank, score or reject candidates yourself.
skill://hiring/jobs#
My Workplace (/mcp/me) · read it before jobs at the company: open jobs, sharing a job with your link, referring someone, your referrals, your interviewing week, interviews and part in hiring
Read the skill
Jobs at the company#
When the company uses Bizisy's Hiring, everyone who works there sees its open jobs (hiring_jobs_open_list_me): title, team, place, contract, the pay range the post shows, its careers page, and how many people applied with your link.
- Share a job: hiring_share_link gives your own link (a short code: the company sees how many people applied through your shares; you see the count only, never who) and ready links for LinkedIn, WhatsApp, Facebook, X and email with a message in your language. Nothing is posted for you: the user opens the link and posts it.
- Refer someone (only when the company switched Referrals on): the user does it in Bizisy (My workspace → Jobs → Refer someone) with the person's name and email, after that person agreed to be contacted; they get one email. You can't send it for them.
- hiring_referrals_mine: their referrals' state as one word (invited, applied, in_process, hired, not_this_time, closed) and their bonus when one applies (when it is earned, waiting, due, in payroll — added to their pay for a pay period when the company prepares payroll in Bizisy —, paid or not due). Never ask for or guess anything about the candidates themselves.
- The hiring team of a job (its hiring manager) sees that job's candidates with hiring_applications_list and hiring_applications_get; summarise from facts, never rank or judge candidates.
- Interviewing (when the company runs interviews in Bizisy): hiring_availability_get and hiring_availability_set are your usual week — windows (day 1 Monday … 7 Sunday, on the half hour, in your time zone) when you can usually interview, a weekly cap (interviews, and hours if you want) and a pause. Bizisy books you only inside them, never on your time off or public holidays; each interview's length is set by HR. Invitations arrive by email with a calendar file. Changing your week never moves interviews already booked: tell HR.
- Your interviews (My workspace → Interviewing) show what is coming up and the feedback you owe; the interview kit with the candidate's CV, answers, the job post and the scorecard opens in Bizisy only (hiring_me_interviews and hiring_me_interview are refused over an API key or MCP), and so do writing and sending feedback. You may help the user prepare: what the scorecard's skills mean, which questions fit the job. Never judge or rank the candidate for them.
- Internal jobs (when the company turned them on): open_list_me says for each job its audience (public, internal_first, internal_only), whether you can apply (can_apply) and, if not, why and from when (blocked). Internal posts can't be shared outside. The user applies themselves in Bizisy (My workspace → Jobs → Apply): hiring_internal_apply refuses an API key or MCP, so never apply, withdraw or accept an offer for them. hiring_internal_apply_form tells you what the form will say, including when their manager is told (notice.sentence: the company's rule, earlier if the manager is on the hiring team) — read it to them before they decide. hiring_internal_mine lists their applications as stage words (applied, interviewing, offer, moved, not_this_time, withdrawn, closed) and an offer to accept in Bizisy. Managers: hiring_internal_manager_view shows their reports' applications only once the company's rule says they are told — before that it is empty on purpose; never hint that something might be there.
- hiring_me_contribution: your own part in hiring this year (interviews held and hours, feedback on time, referrals, shares, thanks received, your load against your cap).
skill://training/manage-training#
HR Assistant (/mcp/manage) · read it before keeping the training register: mandatory training rules and who is overdue (remind, exempt), courses, recording who did which training and for how many hours, confirming training people reported, certificates, importing a spreadsheet, the training-hour balance (Portugal: 40 hours a year, credit, what a leaver is paid for) and Anexo C of the Relatório Único.
Read the skill
Training register#
Owners, admins and HR keep it (Manage → Training). People see their own training in My profile → Training and report training they did; managers see the records of the people who report to them (never certificates).
Courses (define once)#
- training_courses_create: title, hours, provider, delivery internal or external, validity_months (certificates expire, e.g. 24 for first aid), pt (Portugal's Anexo C codes: an area from Relatório Único table 30 such as 481 Ciências informáticas, 862 Segurança e higiene no trabalho, 222 Línguas e literaturas estrangeiras; modality, provider type, level and certificate default to Settings → Training: 08, 01 the company itself, 09, 06 attendance certificate), lms (a TalentLMS, 360Learning, Docebo or Moodle course that is this course: completions there add records).
- training_courses_update, training_courses_archive (records stay and keep counting).
Mandatory training (rules)#
- training_rules_create (dry run first: it says how many people it applies to and how many would be overdue): course_id, who (unit_ids — teams include the teams under them —, title_ids, location_ids, legal_entity_ids; people must match each list given; none: everyone), due_from start (within days of their first day, default 30) | joined (within days of joining the group the rule names) | date (by date; people who join later get days), renewal none | certificate (when the course's certificate expires: the default for a course with a validity) | months (renew_months). People already there get the same days from the day the rule is made: nobody is overdue on day one. Up to 200 rules.
- training_rules_list (each rule with people, counts per status and the share done), training_rules_update, training_rules_archive (nobody is due under it any more).
- training_compliance_list: statuses overdue, due_soon (within 30 days, or a renewal within 30 days), due, done, exempt; totals and by rule, team and location; filter by rule_id, course_id, person_id, team_id, location_id, status, q; pages (limit up to 5,000, offset, next_offset). Computed on read: record the completion and it is done at once. waiting_for_hr: a completion the person reported waits for training_records_confirm.
- training_compliance_remind: rule_id and person_ids (up to 200): one email now to each person and their manager; once a day per person and rule; done and exempt people are skipped. Managers may remind their own reports.
- training_compliance_exempt with a reason (private: never shown to managers, the person or machines) / training_compliance_unexempt; ended exemptions stay in the person's history.
- Home lists training_overdue (people overdue, the worst teams).
Records (dry-run first)#
- training_records_create: person_id, course_id (or new_course, or a title for a one-off), start, end (not in the future), hours attended (default the course's), schedule (working, outside, mixed), result (completed, attended, failed: does not count), kind student_worker for hours a student-worker used for classes and exams, initiative worker_credit when the worker chose it under their training credit. It counts at once.
- training_records_import: up to 150 rows (work_email, course or title, start, end, hours, …). All or nothing: dry run first and fix every row with a problem.
- Reports from people (status pending): training_records_confirm (it counts; confirming attests it relates to the job — in Portugal IT, health and safety and languages always do) or training_records_decline with a reason they will see.
- Certificates: in the app only (training_certificates_upload, then certificate_file_id). They are private.
LinkedIn Learning (when the company connected it)#
- Find and assign a course for a skill: training_content_search (text, skill, language, curated: the company's curated
content) → training_content_assign with item_id, person_ids (up to 200) or group_id (org_groups_list), and due_date
(default 4 weeks). Dry run first. Each person gets a task "Complete
" with the link that opens it (single sign-on when set up). HR assigns to anyone; a manager only to the people who report to them. - It ticks itself when LinkedIn's daily report shows it completed (the next morning, not at once), and the training register records it with the course's hours (the first assignment makes the course; change its hours or codes there). Skills tagged on the course are suggested on the person's profile; their manager or HR accepts them.
- Courses people complete on their own wait for HR (status pending, source lms) unless the company chose otherwise in Integrations → LinkedIn Learning → Settings: training_records_confirm_all confirms them in one go.
- Bizisy sends LinkedIn nothing about people and never creates or removes LinkedIn accounts: licences are the company's LinkedIn admin's. Leavers: release their licence in LinkedIn Learning.
Hours (Portugal: Código do Trabalho art. 131–134)#
- training_balance_get (one person), training_balance_summary (everyone, a year, and the share trained: at least 10% of workers a year).
- 40 hours a year for open-ended workers employed at least 3 months in it (part-time too); fixed-term contracts of 3 months or more a share by months. Training may be brought forward or deferred by up to 2 years: hours go to the oldest open year first. Hours not given by then become a training credit (the worker uses it, with 10 days' notice), which lapses 3 years later. Bizisy shows the larger amount when the law is unclear.
- Settings → Training count_from: years before it are taken as met (training_settings_update). Set it earlier and import past records to see older balances.
- A leaver: training_balance_get's leaving says the hours to pay on the final pay (art. 134). Never tell the person or their manager before HR has told them they are leaving.
Relatório Único Anexo C#
country_relatorio_unico_readiness lists what Anexo C misses (an area on a course, a NISS); country_relatorio_unico_generate makes the file from the register while Training is on.
skill://training/my-training#
My Workplace (/mcp/me) · read it before seeing the mandatory training required for you and its due dates, your training, your training hours and credit, and reporting training you did.
Read the skill
My training#
- training_me_list: your hours this year (owed, given, open), earlier years, your training credit and when it lapses, your records and your reports waiting for HR.
- training_me_list required: mandatory training your company asks of you (by role, team, location), with the date to do it by and its status (overdue, due_soon, due, done, exempt). Once you have done it, HR records it, or you report it.
- If people report to you, training_compliance_list shows their mandatory training (no exemption reasons) and training_compliance_remind sends them (and nobody else) a reminder email, once a day at most.
- Reporting training you did (a course, the hours, a certificate) is done in the app, My profile → Training. It counts once HR confirms it; if HR declines it you see why.
- In Portugal you are owed at least 40 hours of training a year (a share on a fixed-term contract of 3 months or more). Hours your employer does not give within 2 years become a training credit you can use on your own initiative, with 10 days' notice; it lapses 3 years later.
- If people report to you, training_records_list with person_id shows their training.
- LinkedIn Learning (when your company connected it, training_me_list library): training_content_search finds courses (text, a skill, a language); open one with its launch_url. Nothing is recorded until LinkedIn's daily report shows you completed it; then HR confirms it (unless your company counts them at once). Managers can assign a course to the people who report to them with training_content_assign.
skill://benefits/manage-benefits#
HR Assistant (/mcp/manage) · read it before setting up and running the company's benefits: the catalogue with country tax-free limits, flexible plans, enrolment windows, who has what, and what payroll gets.
Read the skill
Benefits#
Bizisy is not a payroll engine: tax-free limits are estimates from each country's rules (with their source and date); the payroll provider applies the final tax. Always say "estimated" and never give tax advice.
Set up#
- benefits_catalogue_add_usual: the common benefits for the company's countries (Portugal, Spain so far), with amounts at the tax-free limit. "Set up the usual benefits for our Portuguese and Spanish entities" = run it with dry_run, show the preview, then run it for real once HR agrees.
- benefits_catalogue_create: one benefit; only type is required (the amount defaults to the tax-free limit, entities to those whose country has a rule, funding per type). funding: employer (company pays, everyone eligible has it), flex (from the person's flexible budget), sacrifice (from gross pay), employee (the person pays). Eligibility: group_id (a saved group from org_groups_list) and wait_days.
- benefits_plans_save: the flexible budget per legal entity (one plan each); prorate for joiners and part-time.
- benefits_windows_open: open enrolment for entities (default: today for 30 days, choices from the 1st of the next month). New joiners get their own window from their first day (benefits_settings_update joiner_days).
- benefits_settings_get: per country, what the company must do for the tax-free treatment to hold (offer it to everyone eligible, give it on top of pay, Spain's salary-change agreement). Tell HR these; never assume them.
Run#
- benefits_people_list (app only): who has which benefit and who has not chosen in an open window.
- Payroll picks benefits up by itself in each period (a "Benefits" group, split into tax-free and taxable parts, with the codes set on each benefit: codes for the tax-free part, codes_taxable for the taxable one).
- People choose their own in Me (benefits_me_choose); HR does not change someone else's choices here.
skill://benefits/my-benefits#
My Workplace (/mcp/me) · read it before explaining your benefits: what the company gives you, your flexible budget and choices, and the tax-free limits.
Read the skill
My benefits#
- benefits_me_get: what you have, your flexible budget (this year, used, left), your choices and each country's tax-free limit with its source, and whether you can change them now (your new-joiner window or open enrolment) or from when.
- Changing choices happens in the app (Me → My benefits); point the person there.
Explain limits as estimates ("tax-free up to €10.46 a day worked; above that it is taxed as pay, estimated; your payroll provider applies the final tax"). Never advise what to choose and never compute net pay.
skill://surveys/manage-surveys#
HR Assistant (/mcp/manage) · read it before building surveys, sending them to people in the company and reading their results within the confidentiality rules.
Read the skill
Surveys#
Two modes, chosen when the survey is made and fixed once it opens:
- confidential (default): Bizisy knows who answered (for reminders and segments) but nobody, owners included, ever sees one person's answers. Results hide any group smaller than the threshold (default 5, never below 3) and show comments only from the comment threshold (default 10), masked. A group that subtracting others would reveal is hidden too (under null), and results move only in steps of the threshold (included says how many answers count so far). Who answered and when is never shown. The same rules apply to you: never try to narrow results to find someone.
- named: answers carry the person's name (event sign-ups, forms). surveys_results_responses lists them.
- anonymous: no link from an answer to a person at all (one-time tokens; only the coarse bands in anonymous_bands — team, location, tenure — are kept). Nobody knows who answered, so reminders go to everyone and erase can't find answers. Say "anonymous" only for this mode; confidential is not anonymous.
Listening
- surveys_library_list: sourced questions with stable ids and drivers; surveys_surveys_create with template (enps, engagement, pulse) starts a listening survey in six languages. Keep library_id on copied questions.
- Recurring: surveys_surveys_open with recurrence { every: week | two_weeks | month | quarter | half_year | year, open_days }; each round is its own survey (series_id, round_no); surveys_series_stop ends it.
- Fatigue guard: surveys_settings_get/update (max_per_month, default 2); surveys_audience_count says how many are at the cap; they are left out unless ignore_fatigue.
- manager_view (before sending): managers read their own line in My workspace, never a sub-line the guard hides.
- surveys_results_heatmap: drivers and questions × team, manager line, location, entity, tenure band or an analytics custom field (by: field + field_key); filter combines a second group and doubles the floor. surveys_results_trend: every round of a series. surveys_results_drivers: correlation with eNPS (association, never cause: say so).
Building
- surveys_surveys_create: a draft (title, mode, language; optionally the whole definition).
- surveys_surveys_get / surveys_surveys_update: the definition is pages of questions. Types: single, multi, dropdown,
nps (0–10, eNPS), likert (5 or 7 points, low_label/high_label), star, emoji, slider (min/max/step), ranking, matrix (rows ×
choices), short_text, long_text, number, date, yes_no, people (named only), location, statement, consent.
Logic: show_if on a question (rules on earlier answers, variables or the person's team/location/entity/language), jumps
after a page (to a later page id or "end"). Piping in texts and choice labels: { {answer:
}}, { {person:first_name}}, { {person:team}}, { {person:location}}, { {var: }}. Scoring: variables, score_into on a question (choice score or the number answered × weight), outcomes (first whose condition holds) on the thank-you screen. Choices: randomize, other, quota (seats). Translations: definition.languages and definition.translations[lang][key] with keys like "q: :title", "c: : ", "cover:title"; missing ones fall back to the source language. Fix everything surveys_surveys_get lists under problems before sending. - Once a survey has opened only the title, translations, reminders and close date change: duplicate it to change more.
Sending
- surveys_audience_count: how many people an audience reaches (everyone, unit_ids with sub-teams, location_ids, entity_ids, group_ids).
- surveys_surveys_open: now, or at open_at (scheduled); close_at closes it by itself; reminder_days (at most 2) remind those who haven't answered. surveys_surveys_close closes it (or cancels a schedule). Try it with dry_run first.
Results
- surveys_results_get: response rate overall and by team, location and entity; per question counts, shares, averages, eNPS (promoters 9–10 minus detractors 0–6), rankings and comments. segment narrows to one team, location or entity. hidden: true with under N means fewer than N answered (say so); with under null, the group is hidden so a smaller group can't be worked out by subtraction. Never guess hidden numbers.
- surveys_results_export: CSV or XLSX with the same rules.
- surveys_results_responses: named surveys only.
skill://surveys/my-surveys#
My Workplace (/mcp/me) · read it before the surveys sent to me: which wait for my answers and when they close.
Read the skill
My surveys#
- surveys_me_list: the surveys sent to me (new, started, answered) with when they close; to_answer counts those waiting.
- surveys_me_get: one of them, with my saved answers.
- Answering happens in the app (My workspace → Surveys): send the person there; their answers are theirs to give.
- Confidential surveys: nobody at the company sees one person's answers, only results of groups large enough.
skill://talent/manage-talent#
HR Assistant (/mcp/manage) · read it before running performance and talent: review cycles (self, manager, peers, upward), templates and rating scales, release dates, goals and their cascade, calibration sessions, potential, the 9-box, succession for key positions, the skills framework and talent profiles (education, certificates, experience).
Read the skill
Performance and talent#
Owners, admins and HR run it (Manage → Talent); managers write their reports' reviews and goals; people see their own reviews only on the release date. Ratings, potential and readiness are human judgements: you can explain the process, organise and remind, but API keys and AI assistants never read or write answers, ratings, potential, calibration or succession, and never learn who gave which feedback.
Settings (talent_settings_get / talent_settings_update)#
- Rating scale (default 5 points: Well below, Below, Meets, Exceeds expectations, Outstanding), an optional calibration reference curve (none by default; when HR sets one, information only, never a quota; don't suggest forcing a distribution), the anonymity threshold (3–10, never below 3), second-level sign-off, the potential prompts, retention (default 5 years after a cycle closes) and the works council checklist for the countries of the legal entities. The checklist is informational: never give legal advice; tell HR to check with their representatives.
Review cycles (owners, admins and HR)#
- talent_templates_list: the company's templates and the starters (Annual review, Mid-year check, Probation review, Project 360). talent_templates_save keeps a starter or a new one (steps self, manager, peer, upward; questions; texts.self words a question for the self-review in the first person, "What should you keep doing?"; overall_rating false makes it development only: no overall rating, no calibration, salary reviews treat people as "No rating". The Mid-year check and Project 360 starters are development only; Annual review and Probation review are rated).
- talent_cycles_create makes a draft: name, template_id, population (teams, sites, titles, levels or a list; minimum tenure, default 90 days), dates (start, nominate_by and peer_due with peers, self_due, manager_due, calibrate_by, release_on, in order), upward, potential_step, uses_calibration. Show HR its preview: people per team, who is left out and why, people without a manager, the emails, the checklist. A good default when HR just says "our annual review": everyone, starter:annual, start the next Monday, 5 weeks (peers chosen by day ~4, self and peer feedback due ~day 16, manager review ~day 24, calibration by ~day 31, release on day 35), potential_step and uses_calibration on. talent_cycles_preview_email shows each email as it is sent (app only).
- talent_cycles_launch (dry-run first). when: "start" waits for a future start date (the emails go out that morning; until then the draft can change or be cancelled; scheduled_on shows it, schedule_problem says why it couldn't start). Large cycles write 200 reviews at a time; talent_cycles_launch_continue or the hourly sweep finish it.
- Follow with talent_cycles_get (progress by team and step, overdue) and talent_cycles_remind (once a day).
- talent_cycles_close from the release date; talent_cycles_cancel before it (nothing is ever released then).
Reviews#
- Reviews are written in the Bizisy app only: API keys and AI assistants can't read answers or ratings, write reviews or feedback, or learn who gave feedback. talent_reviews_list gives statuses (to do, done, left) to organise and remind.
- The person sees their review from the release date, once the manager submitted (and second-level sign-off, and a locked calibration, when on). Before that they learn nothing about its status: never tell them.
- HR can give a review to another reviewer (talent_reviews_reassign) and reopen a step before the release date (talent_reviews_reopen), both with a reason.
Peer and upward feedback#
- The person chooses 3–8 colleagues by the nomination date; their manager approves, swaps or adds (talent_feedback_decide); HR can add (talent_feedback_add). A colleague is asked at most 12 times a cycle.
- Answers show only as a group of at least the threshold, unattributed and shuffled; below it they are withheld from everyone, HR included. Nobody ever learns who answered or declined.
Goals#
- talent_goals_create: company (HR), team (HR or the team's managers) and person goals (the person or their direct manager; higher managers read them), aligned one level up (at most 4 levels), with 0–5 key results or a manual percent. talent_goals_progress records progress (via one_on_one or check_in when it comes from a 1:1 or a check-in). Person goals are private to the person, their managers and HR unless shared.
- Goals from a quarterly check-in: read the answer to its goals question (org_check_ins_get), propose one goal per line for the quarter after the check-in, confirm the titles with the person or manager, then create each with talent_goals_create (skip one already set for that period).
- Suggested measures: when the company switched goal suggestions on (Settings → Talent; an owner accepts the AI features addendum), a person writing a goal can ask Bizisy for measures in the app (talent_goals_suggest_measures, app only, by the tokens used in AI credits, 20 a day). Only the goal's title and description are sent; nothing is saved until the person adds a suggestion. You can't call it: help the person write measurable key results yourself instead.
Calibration sessions#
Why: a manager's rating says as much about the manager as about the person; a calibration session applies one standard across managers. HR creates a session for people of one launched cycle (by team, site, title, level or a list; up to 500; each person in one session per cycle) with talent_calibrations_create, names a facilitator (owner, admin or HR) and participants (by default the population's managers). Nobody in the population may facilitate or take part. For a large population, HR doesn't build sessions by hand: Manage → Talent → Calibration suggests one per department of at most 40 people (talent_calibrations_suggest; a big department is split into balanced parts that keep each manager's team together; departments under 5 people are pooled) and creates them all in one click (talent_calibrations_create_suggested, all or nothing). HR opens it (talent_calibrations_open: participants get an email). In the room, people move ratings and potential with a reason of 10–500 characters; the manager's original rating stays visible. The room shows a compact 9-box (counts, a few faces, how far each box is from the target), the selected box's people (sortable by changes, rating, self-rating and last rating) and a person's evidence (talent_calibrations_evidence: manager's notes, self-review, peer themes above the anonymity threshold, goals, earlier ratings). Participants can hide their own reports to judge the others first. There is no target curve by default; a reference curve HR may set (Settings → Talent) is information, never a quota (never tell people how many must move to match it): watch the centrality warning, since sessions tend to pull people to the middle. The facilitator locks it (talent_calibrations_lock): current ratings become final; HR can reopen with a reason until the cycle's release date. Moving, locking, reopening and the room itself are app only: you can help organise a session (who, when, which filters) but never see or change ratings, potential or reasons.
Ratings by sex#
Ratings decide raises, so EU pay transparency rules expect them to be objective and gender-neutral (Directive 2023/970 arts. 4(4), 6). On the review cycle page and in the calibration room HR runs "Check ratings by sex" (talent_cycles_sex_check, app only): shares of women and men at each rating and potential level, the mean rating gap, top and bottom ratings, High potential and calibration moves up and down, for the cycle and each session, from the sex recorded for equal-pay reporting. Groups with fewer than 5 women or men are hidden. A flag (women-to-men ratio outside 0.8–1.25, or a mean gap of 5 % of the scale or more) is a reason to look at the ratings and their reasons, not proof of bias. Suggest HR runs it before locking a session and before a salary review uses the ratings; you never see the figures.
Potential#
The direct manager or HR assesses it (low, moderate, high) after answering three prompts: aspiration (wants more responsibility), ability (learns fast, handles the next level's complexity) and engagement (committed, likely to stay). Potential ratings tend to favour people like the rater: rate what you have seen, not style or availability for long hours. The person never sees their potential in My workspace. App only.
The 9-box#
Performance (the latest calibrated rating, in three bands) against potential. Box names describe the box ("High performance, moderate potential"), never the person: do not call people "stars" or "problems". Use it to plan development and succession, not as a label. HR sees everyone but themselves; managers their reports; with fewer than 3 people in a filter only the total shows. App only.
Succession#
HR marks key positions (a job title, optionally in one team) with why it is key, impact of loss and the holder's risk of loss. To start, Manage → Talent → Succession suggests roles from the org chart (talent_succession_positions_suggest: managers of 10+ people, titles whose holder left in the past year, titles one person holds) that HR ticks and marks in one go (talent_succession_positions_mark_suggested); impact and risk are changed in the table. HR names up to 10 successors each as ready now, ready in 1–2 years or ready in 3+ years. Bench strength: Covered (someone ready now), Thin, Uncovered; the company's bench strength is the share covered. Bizisy never tells anyone they are a successor or that their role is on the list, and nobody sees a plan where they are the incumbent or a successor (the owner excepted). Development actions (talent_dev_actions_save: stretch assignment, mentoring, course, other) grow people; a course action is done by itself once a confirmed training record of that course exists. Plans are app only; development action titles and due dates can be read for the caller's own.
Skills#
One catalog (talent_skills_list; the starter set with talent_skills_starter), levels 1 Foundation, 2 Working, 3 Advanced, 4 Expert. HR sets what each job title requires (talent_skills_required_set) and what courses give (talent_skills_courses_set). People hold skills as self-assessed (shown as such), from their manager (counts for gaps), from training (derived from confirmed records) or inferred (suggestions that count only once a manager or HR accepts them). talent_skills_gaps shows a team's required skills against the level that counts.
Talent profiles#
Settings → Talent → Talent profiles (talent_settings_update profiles: { on, colleagues }), off by default. Each
person's profile: history and courses from the records, the skills that count, and education, certificates and
earlier experience added by the person or HR. HR (owners, admins, HR) adds or changes entries for anyone
(talent_profile_entries_add with person_id: shown as added by HR; over an API key or AI app only on profiles shown to colleagues) and marks entries verified in the app only
(talent_profile_entries_verify refuses API keys and AI apps, and nobody verifies their own). Managers read their
reports' profiles and set skill levels (talent_person_skills_set); they don't write entries.
- Over an API key or AI app you see a person's profile only when they show it to colleagues, as colleagues see it (no about text, earlier experience or certificate numbers). Don't try to work around a "not found".
- Profiles are facts people stated: never infer studies, levels or ambitions from other data, and never rank people by their profile. Search and internal candidates come later; until then answer from profiles you can open.
- A PT person's Relatório Único education code (country data) is suggested from a completed degree on their profile in Integrations → Country obligations → Country data; HR checks and sets it (country_facts_set). Never set it unasked.
skill://talent/manage-career-paths#
HR Assistant (/mcp/manage) · read it before setting up career paths between job titles (Settings → Career paths): adding, suggesting, changing and removing them.
Read the skill
Career paths#
A path links two catalog job titles (not positions): from → to, kind (promotion, lateral, specialist), typical months in the starting title and a note people read in My career. Owners, admins, HR (or a custom role with Structure at Edit) and their API keys may write; everyone but viewers reads.
- talent_paths_list (family_id, or "none"; title_id) — paths with the skills each target title requires; counts per family and the limits (200 per family, 2,000 in all).
- talent_paths_suggest — proposes the next level up in the same family and track for every title (from the job title
catalog: titles need a family, track and level; set them with org_titles_update).
create: falselists,create: trueadds them (or onlypairs). Deterministic, not AI. Always show the list and ask before creating. - talent_paths_set — add (from_title_id, to_title_id) or change (path_id). One path per pair; active titles only. Use dry run to preview.
- talent_paths_remove — removes a path; people's interest stays.
- Required skills per title are set in Talent → Skills (talent_skills_required_set), courses' skills with talent_skills_courses_set: both feed the gaps and suggested courses people see.
- Career interest (talent_paths_interest_list) stays in the app: API keys and AI assistants can't read it.
skill://talent/my-reviews#
My Workplace (/mcp/me) · read it before helping someone with their own reviews, feedback requests, goals, skills and development: what to do by when, how to write useful feedback, how anonymity and release work.
Read the skill
My reviews, feedback and goals#
talent_me_home says what is waiting: self-reviews and their due dates, peers to choose, feedback colleagues asked for, reviews ready to read, open goals, and for managers the reviews to write.
What you can and can't do here#
- You can explain the process, list what is due and help the person plan and draft their thoughts in the conversation.
- Writing and sending a self-review, choosing peers, giving feedback, acknowledging or commenting on a review happen in the Bizisy app (My workspace → My reviews): point them there. You can't read review answers or ratings.
Release#
- A review is shown to the person from its release date, once their manager has submitted it (and signed off and calibrated where the company does). Before that, only the date is known: never guess or hint at a status or rating.
- After release they can mark it as read (that is not agreeing), add a comment that stays with the review, and ask to discuss it, which adds a topic to their next 1:1.
Giving feedback#
- Answers are shown only as a group of at least the company's threshold (3 or more), never with names, in no particular order. Declining needs no reason.
- Good feedback is specific and kind: what they saw, an example, the effect, and one thing to keep or change.
Goals#
- talent_goals_list shows their goals and the team and company goals they can align to; talent_goals_progress updates progress (key result values or a percent, a status, a note). Personal goals are private to them, their managers and HR unless they share them.
skill://talent/my-career#
My Workplace (/mcp/me) · read it before answering "what jobs can I move to?", "what do I need for the next level?" and "which courses help?" for the person signed in, from their career paths; and keeping their talent profile (education, certificates, experience).
Read the skill
My career#
Use talent_paths_mine (the person's own data only). It returns:
title: their job title today in the catalog (null: HR hasn't put it in the catalog; say so and suggest asking HR).required: the skills their job needs, held vs needed (levels 1 Foundation, 2 Working, 3 Advanced, 4 Expert).paths: per target title —kind(promotion, lateral move, specialist),typical_months, HR'snote,gaps(biggest first; status met, below or missing),courses(up to 3 per gap skill, completed ones left out),jobs(open internal jobs for that title) andinterest(they said they are interested).
How to answer:
- Lead with the paths and the 1–3 biggest gaps for each, in plain words ("System design: you're at Foundation, Senior Backend Engineer needs Advanced"). Mention a course only if one is listed; never invent one.
- Only accepted skills count, and the manager's level counts over the person's own: if they think a level is wrong, tell them to update My skills and ask their manager to confirm.
- Open jobs: point to Me → Jobs. Never apply for the person.
- "I'm interested" and sharing it with the manager are said by the person in the app (My career): you can't do it for them (talent_paths_interest_set refuses API keys and AI assistants). Explain that HR sees interest and the manager only if they share it; it is a signal for development, never a decision.
- No paths for their title: say HR hasn't set them yet and suggest talking to their manager.
My talent profile#
Use talent_profile_get without person_id for the person's own profile: headline, history in the company and courses
done (from the records, nobody types them), the skills that count, and what they or HR added — education
(qualification, institution, ISCED 2011 level 1–8, ISCED-F 2013 field, status done / in_progress / paused, years),
credentials (certificates and licences; the number is never shown to you) and experience before joining.
settings.on false: the company doesn't use talent profiles; say so and suggest asking HR.
- "Add my accounting degree, I finish in 2027": talent_profile_entries_add with
entry: { kind: 'education', qualification, status: 'in_progress', end_year: 2027 }, plusisced_level(6 bachelor's / licenciatura, 7 master's, 8 doctorate) andisced_field(e.g. 0411 Accounting and taxation, 0413 Management and administration) only when you are sure. Read the entry back to the person before adding it. Never sendcredential_id(refused): the person adds certificate numbers in the app. - Change or remove an entry with talent_profile_entries_update / talent_profile_entries_remove (ids from the profile). A change clears HR's verification; say so.
- Who sees the profile (HR and managers, or also colleagues), the headline and "about" are the person's choice in the app (My career → Profile): talent_profile_update refuses AI assistants. Explain the choice; don't make it for them.
- A colleague's profile shows only when that colleague chose to show it (otherwise "not found", the same as an unknown person): never guess why.
skill://comp/salary-reviews#
HR Assistant (/mcp/manage) · read it before explaining or organising salary reviews: the cycle's stages and dates, the merit matrix (rating × compa-ratio), budgets, how proposals are approved and released, and the criteria published to staff.
Read the skill
Salary reviews#
Owners, admins and HR run salary reviews in Bizisy (Manage → Salary reviews). Pay never leaves the app: API keys and AI assistants see a cycle's name, dates and stage only (comp_cycles_list). Never propose, change, approve or release pay, and never guess anyone's raise: you can explain the process, the dates and the criteria, and remind people of what is due. Hand every pay step to a person in the app.
Stages#
- Draft — HR sets the population (company, teams, legal entities), eligibility (employed on the cut-off date, default 3 months before the effective date), the effective date of the new pay, the dates (proposals due, HR review by, managers' preview, release), the merit matrix and the merit pool (% of eligible annual base, per team if needed). Optional: a separate promotion pool (% of base; raises with the reason "promotion pending" draw on it) and a lump-sum pool (an amount per currency, no FX) that turns on one-off lump sums. With lump sums on, pay above the band maximum gets its guideline raise suggested as a lump sum instead of a base increase (can be switched off).
- Criteria — before launch HR publishes the criteria to staff (EU Pay Transparency Directive art. 6: the matrix, the pool as a %, the reasons list), or records that they were shared another way. Staff read them in My workspace → Pay → "How pay progresses" (comp_me_criteria).
- Launch — Bizisy snapshots each person's pay on the effective date (base, band, compa-ratio = pay ÷ band midpoint, the final rating from a talent review cycle when one is set) and gives each manager a worksheet.
- Proposing — managers propose a % per person within the guideline and budget; outside the guideline needs a reason (market, retention, internal equity, promotion pending, skills, other). Managers never see salaries, only compa-ratio bands, position in range and budget as % used. With lump sums on, a manager may add a one-off lump sum per person, typed as % of base (HR sees the amount). Each pool (merit, promotion, lump sums) shows its own meter; submitting over any of them needs a reason for HR. Nobody is told they are in a review. Two cycle options, both off by default and fixed at launch: amounts (managers also see their team's current and new base pay and the budget in money while the review is open; each view is recorded in Activity) and the manager's manager check (a submitted worksheet goes first to the manager's own manager, who reads it in %, may change a proposal and sends it on to HR or back; HR can take a waiting worksheet on without that check).
- Review — HR approves rows. Each row follows the pay approval rules: owners, admins and HR; an HR member's pay only owners and admins; an owner's only another owner; never your own, never a row you proposed or changed. Optional final sign-off (off by default, fixed at launch): owners, or a custom role with Pay at Approve over everyone in the review (a "Finance" role), check the totals per team and currency against the budget and the equity check (comp_signoff_get) and sign off or send back to HR with a note; the release waits for it, and a change to an approved row afterwards needs it again. Nobody signs off a review with a raise of their own in it.
- Preview — from the preview day managers see the final outcome of their rows, to prepare conversations.
- Release — on the release date (08:00 company time) or "Release now": approved raises are written to pay from the effective date (re-checked: still employed, pay unchanged since the snapshot), payroll picks them up, and each person gets a letter in My workspace → Pay with an email that has no amounts. With Documents on, the letter is also a PDF in their My documents (template "Pay review letter": copy it in Documents → Templates to use your own words), sent a few at a time after the release; one that can't go (a value missing, on paper) waits in Documents for HR, and the cycle's Release tab counts them (comp_cycles_get letters). Lump sums are in the letter (never in the email). With Payroll on, each lump sum becomes a "Salary review lump sum" pay item in the pay period of the effective date; without Payroll, or when Payroll can't take it (no pay schedule for the person), HR pays it by hand, finds it in the payroll file (comp_cycles_export, lump_sum_payment = by_hand) and marks it paid in the app.
The equity check (comp_review_equity) counts lump sums as pay (variable pay, Directive art. 3): a separate gap on them, next to the base pay gap.
A pay change made outside the review during it sends that person's row back to HR ("stale").
Before release, the Equity check tab shows HR the projected pay gap by category (comp_review_equity) and, on request, the ratings feeding the matrix and the raise proposed at each rating by sex (comp_review_rating_check: totals only, hidden under 5 women or men; a raise gap of 0.5 points at equal rating or more is flagged). Both are app only: suggest HR runs them before approving, and never guess the figures.
Protected leave#
People on maternity, paternity, parental or adoption leave in the review period (the 12 months before the effective date, from Time off's family leave types) are in the review like everyone and get the raise as if they had been at work (EU Directive 2006/54 art. 15, Directive 2019/1158 art. 10, CJEU Gillespie). Their row is flagged "Protected leave" (never the kind of leave) and starts at its floor: the guideline target for their rating, or without a rating the average increase the cycle funds when higher. Less is refused unless HR records an objective reason unrelated to the leave. Their letter goes out like anyone's. Never suggest a lower raise because someone was away on such leave.
Bonus plans#
Owners, admins and HR also run bonus plans (Manage → Bonus plans; comp_bonus_plans_list gives names, dates and status only). Bonus = annual base pay × target % × company factor × individual factor × share of the period worked, in cents, rounded once (half up). Defaults: target 10 % (other targets per job title), company factor 100 % (may be set later, when the year's results are known; approving and paying wait for it), individual factor from the final calibrated rating of a review cycle (0 / 50 / 100 / 120 / 150 % on a 1–5 scale; "No rating" 100 %, so nobody gets 0 for a missing rating), at most 200 %. Goals count only if HR gives them a share (default 0 %) and only goals HR marked committed (OKRs are meant to be ambitious: advise against tying pay to them). Maternity, paternity, birth, adoption and parental leave always count as time worked; the plan chooses whether other unpaid leave does (default yes). Steps: draft with a live preview worked through on a real person → publish the formula to staff (required before launch, EU Pay Transparency Directive art. 6) → launch (awards by the formula) → managers may move their reports' awards within ± the plan's range (default 0: formula only), in %, with a reason → HR checks the equal-pay view (comp_bonus_equity: average award and award ÷ target by sex per category; 5 % or more flagged) and approves each award under the pay approval rules → release on the payout day at 08:00 (or "Release now"): a "Bonus" item in Payroll once per award, or by hand and marked paid, and a letter in My workspace → Pay with an email without amounts. Never propose, change, approve or release a bonus, and never guess anyone's award.
skill://comp/my-salary-review#
My Workplace (/mcp/me) · read it before helping a manager with their salary review worksheet, or anyone with how pay progresses and their pay letters.
Read the skill
Salary reviews in My workspace#
- Managers propose raises for their team in My workspace → Salary review: a % per person within the guideline range shown (above the band maximum, often as a one-off lump sum in %), a reason when outside it ("promotion pending" draws on the promotion budget when there is one), then Submit. A row marked "Protected leave" can't go below the % shown (the raise as if the person had been at work); only HR can record an objective reason for less. When HR turned on the manager's manager check, the worksheet goes to their own manager first; a manager's manager finds their team leads' worksheets on the same page ("From your team leads"). When the review shows managers pay, each time they open it is recorded. Worksheets and letters are in the app only: you can explain the guideline, the reasons list and the due date, and remind them, but never read, propose or submit pay.
- Everyone can read the criteria HR published (comp_me_criteria): the merit matrix, the pools as a % and whether one-off lump sums are part of it. Letters (My workspace → Pay → Letters) appear only once a review is released; with Documents on, also as a PDF in My documents (comp_letters_get document).
- Bonus plans: a manager may adjust their reports' bonus awards in My workspace → Team bonuses while a plan is open, as a % of the formula within the plan's range and with a reason; never amounts, never their own. Everyone reads the published bonus formula under "How pay progresses" (comp_me_bonus_criteria, % only). Bonus letters appear with the other letters once a plan is released.
skill://insights/talent-insights#
HR Assistant (/mcp/manage) · read it before questions about attrition risk, flight risk, "who might leave", talent insights or skill suggestions
Read the skill
Talent insights#
Talent insights (an optional module each company switches on) works out an advisory band (Low, Elevated, High or Limited data) per employee from job data by published rules, so HR can start a conversation. It is a high-risk AI system under the EU AI Act, and Bizisy keeps every band inside the app, read by a person:
- You cannot read bands, factors, the list, explanation requests or the audit log: those actions refuse API keys and AI assistants ("Do not retry"). Never guess or infer who has a band.
- If someone asks who might leave, send them to Talent → Insights in Bizisy, and remind them: a band is a reason to talk, never a decision; never tell a person they have a score; never use it alone for pay, promotion, discipline or dismissal.
- You may read
insights_settings_getto explain whether the company uses it and which setup step is next (no person data). - Employees can object or ask for an explanation themselves in My workspace → Privacy & data → AI insights.
- Setup step 6 is a back-test on the company's own history (people who left by choice in the last 24 months, their
band 90 days before leaving, against people who stayed; also by recorded sex and age band). HR runs it and an owner or
admin acknowledges the results in Settings → Talent insights; it runs again every 3 months and, if a new result is not
acknowledged within 30 days, new bands wait. You can say whether it is done (
insights_settings_getbacktest), never run or acknowledge it. - Skill suggestions (no AI credits, rule-based, no language model): Bizisy matches a person's certificates (a document category with an expiry date, never health-related ones) to the company's skills by name, notes when their title requires the skill, and suggests it with that evidence. A suggestion never counts until HR or the person's manager accepts it (Talent → Skills); a rejected one is not suggested again for 12 months. People who objected get none.
skill://insights/my-ai-insights#
My Workplace (/mcp/me) · read it before questions about AI insights about me, objecting to profiling or asking for an explanation
Read the skill
AI insights about me#
insights_me_get says whether the person's company uses Talent insights, the notice it sent, whether they are included
or objected, and their latest explanation request. It never returns a band: their band (if any) is in their data
download. Objecting and asking for an explanation are the person's own clicks in My workspace → Privacy & data → AI
insights: send them there; you cannot do it for them.
skill://migration/move-from-another-tool#
HR Assistant (/mcp/manage) · read it before adding people from a spreadsheet (People → Import: one name column is fine) or moving a company's people from Personio, Factorial, Sesame HR, HiBob, BambooHR or Meta4 PeopleNet into Bizisy: the people file as CSV text, the dry-run report, fixing rows, importing and undoing; and leaving: where to export for Personio or another tool.
Read the skill
Migrate from Personio (or any HR tool) with your AI#
Owners, admins and HR move a company (migration.manage), and so does a custom role with Setup and imports at Edit (an Implementation partner's role): such a role sees only the moves it started, moves from export files or text (not an old tool's API), and leaves out pay, payroll identifiers and private details unless it has Pay and Private details at Edit. Accountants and HR partners have no Setup and imports, so they can't move people in. You help them do it from the old tool's people export, and HR stays in charge: you show what Bizisy would do, they decide.
What you can move, and what happens in the app#
- Over an API key or an AI app: one people export as CSV text (at most 1 MB and 250 people). People, teams, locations, managers and custom fields that aren't private. The import runs at once.
- In the app only: bigger files (CSV or .xlsx, up to 10,000 rows), a second time-off file (leave and balances), API connections to the old tool (job history, documents), pay, payroll identifiers (tax ID, social security number, IBAN), sex and private details (birthday, personal email and phone). Point the person to Manage → People → Import (the import wizard, /people/import/move?tool=other for a spreadsheet) for these; columns of these kinds are refused here, never sent another way. This is Bizisy's one way to add people from a spreadsheet; "Update people from a file" (org_imports_*) takes Bizisy's own column names and is for changing people already in Bizisy.
- Never moved: people who already left (termination date in the past, or an inactive status). They are counted in the report. People starting after today arrive as pre-hires; no checklist starts and nobody is emailed.
Steps#
- Ask which tool the export comes from: personio, factorial, sesame, hibob, bamboohr, meta4 (Meta4 PeopleNet), or other (any spreadsheet). Ask for the people export as CSV text (the person can save the file as CSV and paste it, or attach it). Don't rebuild or re-type their file; if you must convert, keep every value as it is.
- migration_start with tool and csv. It reads the header and suggests what each column feeds, with a confidence: exact (the tool's own label), likely (a common name), none.
- migration_get: show the mapping. Read out the columns that are likely or not mapped and the ones that will not be imported, with their sample values, and ask the person to confirm or change them. Private and pay columns show •••.
- migration_check with people_mapping: one entry per column of the file, in order — a target from the run's
targets.people, a custom field "field:
" that isn't private, or null for "don't import". Leave private, payroll and pay columns null (they are refused here); new fields ("new: - Show the dry-run report as it is: people new, updated and unchanged, teams, locations, leavers not moved, columns not imported, and the problems. migration_items with filter fix lists each problem with its row, the file's column and the fix (edit, pick one of options, or skip).
- Fixing: ask the person for the right value, then migration_fix_items (items: the row's id with set: [{ column: the column's index, value }], or skip: true; at most 100 a call; it checks again) and check again; or skip the row if they say so. Never invent a value to make a problem go away: no guessed emails, dates, managers or titles. A problem you can't resolve with them stays, and the row is skipped.
- Ask before importing: "Import 38 new people and update 4? 2 rows are skipped." Only after a clear yes, migration_import. Then show the summary and the next steps: invite people to sign in, check their details, and in the app, time off.
- Undo: within 24 hours the person can undo the import in Bizisy (the move's summary → Undo; migration_undo refuses an API key or AI app): it removes what this import created when nothing changed since; people edited, invited or given a login since are kept and listed. Updates of people already in Bizisy are not reverted.
Good to know#
- A spreadsheet (tool other) may have one name column ("Nome", "Nombre", "Name", "Full name", "Nom complet"; French "Nom" next to "Prénom" is the surname). It feeds the full name, split at the first space: the first word is the first name, the rest the last name ("Ana Maria Costa" → Ana · Maria Costa). The check shows each split (first and last name in the row's changes); to split it elsewhere, fix the row's name cell to "Last name, First name" ("Sousa Costa, Ana Maria") with migration_fix_items. Names can also be corrected on the person's page after the import. Dates are read day first (01/03/2021 is 1 March); without a period column, pay is read per month for a spreadsheet in a company where salaries are monthly (Portugal, Spain…) and per year otherwise (options.pay_period; change it in migration_check).
- Pay (in the app only) follows Settings → Approval rules like org_pay_add: with HR approval for pay changes, each person's pay becomes a request another approver decides (result.pay_waiting counts them; nobody is emailed), or is recorded at once when nobody else can approve. With approvals on, only owners and admins move pay.
- Re-running is safe: people are matched by the old tool's ID, then by work email; teams and locations by name. A second run updates what the first one moved instead of duplicating it.
- A person whose work email changed in the old tool is a problem naming both emails: the email is changed on their page in Bizisy, never by an import.
- People already in Bizisy follow the usual rules: with job approvals on, their job changes are problems ("use Change job"); you never change your own job.
- You see and change only moves you started. Each move is kept 30 days; Activity records counts, never names or values.
Leaving: export for Personio (or Factorial, Sesame HR, HiBob, BambooHR, any spreadsheet)#
When someone asks to export for Personio, move to another tool, or leave Bizisy: this is done in the app only, by an owner or admin (it is a bulk copy of the whole company, so API keys, AI apps, custom roles and partner firms can't make or download it). One export is built at a time. Tell them, without trying to change their mind: in Bizisy open Settings → Data & privacy → Move to another tool (or press ⌘K and type "Export for Personio"), pick the tool, look at the preview (counts and what the tool can't take), choose pay and documents if wanted, and make the export. It is built in the background and they get an email when it is ready; the zip holds the tool's import files, a README with step-by-step instructions in the company's language and a link to the tool's own help, and is downloadable for 7 days. Their data stays in Bizisy until an owner closes the account.
skill://webhooks/webhooks#
HR Assistant (/mcp/manage) · read it before setting up, testing or troubleshooting webhooks (sending Bizisy events to another system): endpoints, event types, secrets, the delivery log
Read the skill
Webhooks#
Webhooks tell another system (payroll, IT provisioning, Zapier, a data warehouse) when something changes in Bizisy. Only owners and admins can manage them.
Set one up#
Adding an endpoint, changing its URL, adding events, turning it on, rolling its secret and deleting it happen in the Bizisy app only (Manage → Integrations → Webhooks), by a signed-in owner or admin; over this connection they are refused. Every owner and admin is emailed when an endpoint is added or sends to a new host.
- Ask which system should receive events and which changes it needs. List the types with webhooks_events_list (person.hired, person.updated, person.job_changed, person.terminated, person.rehired, person.erased, unit., location., legal_entity.*, position.created, position.updated, position.filled, approval.decided, checklist.started, checklist.completed, document.added, document.updated, document.deleted, member.invited, member.joined, member.role_changed) and tell the user what to pick.
- Ask the user to add the endpoint in Integrations → Webhooks; the signing secret is shown to them once, there.
- Then you can send a test event (webhooks_endpoints_test) and check webhooks_deliveries_list after about a minute.
Zapier, Make and n8n#
These apps subscribe for themselves (webhooks_subscriptions_create, a REST hook per trigger) with a Manage API key of an owner or admin, when the user turns a Zap, scenario or workflow on, and unsubscribe when it is turned off. You cannot subscribe or point events anywhere over this connection. To help: tell the user to create a Manage API key in Settings → Integrations → API keys, connect it in the app (Integrations → Zapier, Make or n8n has the steps; the developer docs at /developers/automation explain each app), and pick the Bizisy trigger by event (e.g. person.hired). webhooks_subscriptions_list shows what is subscribed; they also appear in webhooks_endpoints_list with source automation. If one should stop, webhooks_subscriptions_delete removes it (the app's trigger stops receiving events).
What is sent#
A POST with JSON { type, timestamp, data }. data has organization_id, the ids and dates of the change and, for people and structure records and open positions, their public and job details as they are when the attempt is sent (never private or pay data, nor a position's budget or notes). Approval and checklist events carry ids, kinds and dates only; approval.decided is sent once a job change or termination request is approved or rejected, never while it waits. Delivery may repeat (dedupe on webhook-id) and may arrive out of order. Headers follow Standard Webhooks: webhook-id, webhook-timestamp, webhook-signature (v1,<base64 HMAC-SHA256 of "id.timestamp.body">). The receiver must answer 2xx within 10 seconds; redirects are not followed.
Troubleshooting#
- Deliveries are tried 8 times over about a day. error says why: dns, blocked_address (the host resolves to a private address), connection, tls, timeout, redirect, http_status (not 2xx; see response_status).
- After a day of only failures Bizisy turns the endpoint off (disabled_reason failing) and emails owners and admins. Once the receiver is fixed, the user turns it back on in the app; then you can resend what is needed (webhooks_deliveries_resend).
- A leaked secret: turn the endpoint off now (webhooks_endpoints_update enabled false) and ask the user to roll the secret in the app with "Stop the old secret now".
skill://accounting/accounting#
HR Assistant (/mcp/manage) · read it before checking how Bizisy keeps an accounting tool (Xero, Exact Online, Holded, Odoo, Moloni ON) in step: teams as cost centres or tracking, legal entities as companies, people as suppliers, and the monthly headcount-cost journal
Read the skill
Accounting tools#
Bizisy keeps a connected accounting tool in step with its structure. Connecting, settings and journals are done by people in the Bizisy app (Integrations → the tool); over this connection you can read the sync.
What Bizisy does there#
- Teams → the tool's cost dimension: Xero tracking options, Exact Online cost centres, Odoo analytic accounts, Holded line tags (Moloni ON has none). Renamed and archived with the team.
- Legal entities ↔ companies: each Bizisy legal entity is matched to one company (Xero organisation, Exact division, Odoo company, Holded account, Moloni ON company). Nothing syncs to a company that is not matched.
- People as suppliers or contacts (name and work email) only when an owner or admin switched it on.
- A monthly headcount-cost journal: only with the pay consent in Payroll, prepared and approved by HR in the app.
What you can do#
- accounting_overview with connector (xero, exact_nl, exact_be, exact_de, exact_uk, exact_fr, exact_es, holded, odoo, moloni): whether it is connected, its companies and which legal entity each is, each team's dimension and whether it was sent, how many people are linked as suppliers, and whether the journal is set up per company.
- integrations_connections_run to sync now; integrations_connections_get for the last operations.
What stays in the app#
Journals carry pay totals: listing, preparing, approving and discarding them is refused over this connection. Tell the user to open Integrations → the tool → Journals. Never estimate pay figures yourself.
skill://integrations/integrations#
HR Assistant (/mcp/manage) · read it before checking or troubleshooting the tools a company connected to Bizisy (task trackers, identity providers, recruiting, payroll): what is connected, whether it works, what it did
Read the skill
Integrations#
Bizisy connects to other tools a company uses. Each connection belongs to the company; owners and admins connect and disconnect them, owners, admins and HR can read their state.
What you can do#
- integrations_connections_list: every tool this Bizisy server offers, with the company's connection (status, the connected account, health). health.failing true means an owner or admin should look: status error (Bizisy's access stopped working: connect again) or several failures in a row (last_error says why, in words safe to repeat).
- integrations_connections_get: one tool and its last operations (what Bizisy did, the outcome; never anyone's name).
- integrations_connections_run: ask a connected tool to sync now (at most a few times an hour; it also runs hourly).
- integrations_connections_lookup: a connected tool's choices for Bizisy settings (its projects, issue types, teams, sections, statuses), e.g. to set where a checklist task goes (org_checklists_templates_update, destination).
What stays in the Bizisy app#
Connecting (granting access or pasting a token), changing a connection's settings, a new events secret and disconnecting are done by a signed-in owner or admin in Integrations; over this connection they are refused. Tell the user where to go instead of retrying.
Troubleshooting#
- status error: the tool removed Bizisy's access or it expired. An owner or admin connects it again.
- last_error "asked Bizisy to slow down" or "not answering": Bizisy retries by itself, later each time.
- A tool missing from the list is not offered on this server yet; nothing to do.
skill://country/country-obligations#
HR Assistant (/mcp/manage) · read it before helping HR and their accountant with what each country asks of an employer when people join or leave or their pay changes (Segurança Social notices in Portugal, alta/baja and Contrat@ in Spain, DPAE in France), yearly staff reports (Portugal's Relatório Único and its readiness), the vacation map (Portugal's mapa de férias), the country data they need, and payroll tools (Nmbrs, Loket)
Read the skill
Country obligations#
Each legal entity follows the rules of its country. Portugal, Spain and France have their own in Bizisy; other EU and EEA countries follow the EU minimum (written terms within 7 days, Directive (EU) 2019/1152); elsewhere Bizisy has none yet. Bizisy helps HR; it never files anything without a person confirming it.
Read first#
- country_obligations_list: per legal entity, its obligations (authority, law, official source, deadline), how Bizisy helps (send, manual, file, sheet, info), how many need someone now, and how much country data is missing.
- country_notices_list (open: true for what needs someone): hire and leave notices and yearly reports with opens_on, due_on and state (upcoming, due, overdue, failed, sent, skipped). failed has record.error.message: say it as is.
Deadlines worth knowing (say them with the source)#
- Portugal: hire notice to Segurança Social before work starts, accepted from 15 days before (CRC art. 29.º as amended by Decreto-Lei 127/2025); leave notice by the 10th of the next month (CRC art. 32.º, DR 1-A/2011 art. 8.º). From 1 January 2027 (mandatory new model): every change of base pay by the 10th of the next month (pt.pay_change), and the monthly declaração à segurança social is accepted or corrected by the 20th — that one is the accountant's payroll, not Bizisy.
- Relatório Único from 16 March to 15 April of the next year (Portaria 55/2010 art. 4.º), extended by notice in recent years (2026: into May and June) — say "check relatoriounico.pt" for the current window.
- Mapa de férias (Código do Trabalho art. 241.º n.º 9): made by 15 April, posted at each workplace until 31 October.
- Spain: alta before the first day (RD 84/1996); Contrat@ within 10 days (ET art. 8.3); baja within 6 days (RD 643/2026).
- France: DPAE in the 8 days before the hire (Code du travail L1221-10).
Relatório Único: readiness first#
country_relatorio_unico_readiness (from 1 January, on last year) says what is missing, grouped by key, with the records to fix: tell the user plainly, e.g. "2 job titles have no profession code (CPP): Engineer and Office manager". Company codes (CPP, qualification level, category, CAE, establishment number) you may set with country_facts_set when the user gives or confirms them; a person's NISS, sex and birth date are on their profile, and reasons for leaving (pt_ru_motivo_saida, table 27) and for a fixed-term contract (pt_ru_motivo_entrada, table 26) are private: entered in the app. Bizisy makes Anexo A (October), Anexo B (joined or left in the year), with the Training module on Anexo C (continuous training, from the training register: each course needs an area code, table 30; each worker's situation and reference periods come from their training-hour balance) and, when the user confirms there were no strikes, Anexo E. Anexos 0, D and F come from yearly forms (missing keys with subject report: ru0_*, ru_d_*, ru_f_*): country_relatorio_unico_annual_get shows Anexo 0 (turnover, union members on 31 October, posted workers, employer associations from table 08, overtime, capital) and Anexo D (how health and safety at work is organised, staff, programmes; Bizisy prefills each establishment's workers, estimated hours and the work accidents counted from leave types marked as work accidents) with Bizisy's prefill; country_relatorio_unico_providers_list is Anexo F's list of service providers (pages of up to 500: pass next as after). Explain what a form asks and where the answer comes from (accounts, the OSH provider's report), but the forms and providers are saved in the app (Anexo D names health staff; a self-employed provider's NIF and NISS are private). If no leave type is marked as a work accident, say so: HR marks it in Settings → Time off → Leave types, or confirms there were none in Anexo D. The coded detail behind a "yes" in Anexo D (risk agents, exams, vaccines, diseases) and Anexo 0's sections on workers with a disability and unworked hours are completed on the platform after uploading. The files are made in the app (they hold private data), then uploaded with the platform's Launcher, then recorded as sent.
Vacation map#
country_vacation_map_get lists each workplace's map: approved vacation per person, bookings still waiting, its state (due, overdue, posted, changed since posting) and posted versions. A person prints it in the app and posts it; then country_vacation_map_post records it as posted (a new version). Remind the user before 15 April, and again when it changed.
Country data#
country_facts_get lists the codes each obligation needs (employer NISS, CAE, CPP profession codes per job title, CCC, SIRET…) and where they are missing. You may fill in company codes with country_facts_set (legal entity, location, job title) when the user gives them or confirms your suggestion — say which official table a code comes from and never guess a code silently. A person's country data (nationality, education level, place of birth) is private: it is entered in the Bizisy app, not over this connection.
What stays in the Bizisy app#
Preparing a notice (it holds private and pay data), sending it to Segurança Social (HR reviews the exact payload first), the Relatório Único file, and Segurança Social credentials are app-only: tell the user where (Integrations → Country obligations, or → Segurança Social). Over this connection you can record notices made elsewhere as sent (with their receipt number) or as not needed (country_notices_record), and reopen one recorded by mistake.
Payroll tools#
Nmbrs and Loket (the Netherlands) appear in integrations_connections_list when this server offers them: new hires, personal changes and leavers of one legal entity go there hourly. Pay is never sent; birth date, address and IBAN only when an owner or admin allowed it on the connection.
Right to disconnect#
country_disconnect_get shows the company's quiet-hours policy and each country's law (Portugal art. 199.º-A and Spain art. 88: always on; France from 50 and Belgium from 20 people per employer; elsewhere the company decides). With quiet hours, non-urgent emails and push notifications to an employee outside their working time (their work schedule or published shifts, in their time zone) wait for their next working period; notices in the app are never held. Owners and admins change the mode or the policy text people read with country_disconnect_update (dry run first); "off" never switches off what the law requires. country_disconnect_when tells a manager when people they manage receive what they send ("delivered at 09:00"). Never suggest contacting someone outside their working time to get around it; for a real emergency, HR publishes the announcement with urgent_reason.
Something missing or wrong on this page? Write to hello@bizisy.com.