Skip to content

MCP and AI

MCP skills

On this page

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#

  1. 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.
  2. 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.
  3. 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).
  4. 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.
  5. 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 " or "by "; "Verified: " means the organization is linked to that Bizisy company, which vouches for it.

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.

  1. platform_setup_list: the switched-on modules with a wizard, their status and what is missing.
  2. platform_setup_get with 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).
  3. 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.
  4. Record progress with platform_setup_update: steps_done as steps are settled, then finish: "done" (or finish: "skipped" when they keep all the defaults). If a step needs someone outside HR (an accountant, the works council), record open_item.add with that role; Bizisy sends nothing, so tell the person who to ask and what about.
  5. 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#

  1. 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.
  2. 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 }.
  3. 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#

  1. Call platform_whoami. Greet them by first name in one short sentence.
  2. 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.
  3. 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).
  4. 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).
  5. 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#

  1. 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.
  2. 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).
  3. 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).
  4. Teams (units). Only when the company has teams worth naming; skip it otherwise. Use org_setup_apply.
  5. 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.
  6. 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.
  7. 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).
  8. 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.
  9. 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#

  1. Orient. Call platform_whoami, then org_setup_status.
  2. 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.
  3. Read what already exists: org_entities_list, org_locations_list, org_units_list and org_people_list with status "all".
  4. 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.
  5. 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.
  6. 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.
  7. When the user approves, call org_setup_apply again with the same payload and without dry_run. Report the counts.
  8. 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.
  9. 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.
  10. 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#

  1. org_me_get.
  2. 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.
  3. Call it with dry_run=true, show the result, and commit after the user agrees.
  4. 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_. Private details are never in it, and nothing planned after the day it describes (a future last day reads as open, people who start later are not there).

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

  1. 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.
  2. 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).
  3. 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):

  1. 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.
  2. 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.
  3. 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:

  1. 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.
  2. 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).
  3. 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#

  1. 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.
  2. 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.
  3. 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#

  1. 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.
  2. 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: