API reference

Every action of the Bizisy API, 142 in all. This reference is generated from the same action definitions that serve the API, the OpenAPI file and the MCP servers, at every build: it can't describe an action that doesn't exist or miss one that does.

Calling an action#

POST https://api.bizisy.com/v1/<module>/<action>
Authorization: Bearer hrk_…
Content-Type: application/json

{ …input… }

• Success is 200 with the result under data: {"data": …}.
• Reads also answer GET, with the input as query parameters (JSON-encode objects and arrays), unless an input field carries a secret.
• Writes take ?dry_run=true to preview and an Idempotency-Key header to make retries safe.
• Errors share one envelope with a code, a message and a hint.
• Inputs are strict: an unknown field is a validation_failed, with the accepted fields in the hint.

Reading an entry#

• Who can call it: the key audiences (Manage, Me) and roles the action allows, worked out from its permission rule. Web app only marks actions no key or connected app may call; Keys and apps states a limit that applies to them.
• MCP tool: the same action as a tool, and the servers that offer it.
• Input and Returns: every field with its type, constraints and description. Nested objects fold open.
• Examples: curl, Node (18 or later, built-in fetch) and Python (requests), with the request a real client would send, and the response. Examples come from one sample company (ids such as p1 are illustrative): the response repeats what its request sent, and shows what an HR Manage key gets when it reads someone else, so private and pay fields come back null.

Platform#

• Account and API keysWho you are, your API keys, your connected apps and your language.8 actions
• Members and rolesEveryone with access to the company, their roles, and linking logins to people.4 actions
• ActivityThe record of every change, with who made it and through what.2 actions
• Company settingsColours and logo, sign-in methods, company language, account status and storage.10 actions
• NotificationsYour in-app notifications, and which optional notices the company also emails.5 actions
• BillingThe company's plan, billing details, invoices and paying them.7 actions

Organization#

• Setup and importSet up a whole company in one call, or import people from a CSV.4 actions
• Units, locations and legal entitiesDivisions, departments and teams, the places people work and the companies that employ them.13 actions
• PeopleThe directory, one person's profile, profile changes and photos.5 actions
• Jobs and employmentHire, change jobs from a date, terminate, rehire and correct job history.5 actions
• Self-serviceA person's own profile, team, photo and data export (Me keys).6 actions
• Org chartThe org chart on any date, as nodes or as a list.2 actions
• InvitesInvite people to sign in, list and revoke invites.3 actions
• Custom fieldsFields of your own on every person, each with a visibility tier.3 actions
• PayPay history. Reading your own pay works with a key; recording pay happens in the web app.3 actions
• Exports, reports and erasurePeople as CSV, a person's data for an access request, the headcount report and erasing a former employee.4 actions
• Home and remindersWhat needs attention today and the reminder emails before dates come up.4 actions
• Open positionsRoles the company plans to fill: the headcount plan.5 actions
• ApprovalsApproval rules and change requests: list, approve, reject and withdraw.7 actions
• ChecklistsOnboarding, offboarding and custom checklists: templates, runs and tasks.14 actions

Documents#

• DocumentsCompany and person documents: list, upload, change, download and delete; categories.8 actions
• My documentsA person's own documents (Me keys).4 actions
• File fieldsFiles in custom fields of type file, for a person or yourself.5 actions

Webhooks#

• Webhook endpoints and deliveriesEvent types, endpoints, test events and the delivery log.11 actions