API reference
Setup and import
Set up a whole company in one call, set up a module the company switched on (its decisions, recommended defaults and progress), or import people from a CSV: matched to your columns, checked person by person, bad rows parked to fix later.
19 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.
List module setups#
POST/v1/platform/setup.listRead
The setup of every switched-on module that has a setup wizard (spec module-setup-wizards): its status (not_started, in_progress, done), steps done of the total, whether it was finished by keeping all the defaults (skipped), who open items wait on (works council, accountant, IT, DPO, lawyer, managers) and how many prerequisites are missing. Read one with platform.setup.get. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
platform_setup_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
itemsobject[]required9 fields
modulestring (enum)requiredOne of:
timeoff,timeclock,shifts,documents,assets,checkins,renewals,hiring,training,talent,insights,payroll,finance,analytics,pay_equity,comp_reviews,more_integrations,bank_verification,benefits,surveys,assistant.namestringrequiredpathstringrequiredThe wizard in Bizisy (Manage path).
status"not_started" | "in_progress" | "done"requirednot_started, in_progress (some steps done), done (finished in the wizard, defaults kept by skipping, or every step done).
skippedbooleanrequiredFinished with "Skip: keep all the defaults".
steps_doneintegerrequiredsteps_totalintegerrequiredwaiting"works_council" | "accountant" | "it" | "dpo" | "legal" | "managers"[]requiredWho open items wait on.
prereqs_missingintegerrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/platform/setup.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/platform/setup.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/platform/setup.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"items": [
{
"module": "timeoff",
"name": "Time off",
"path": "/time-off/setup",
"status": "in_progress",
"skipped": false,
"steps_done": 2,
"steps_total": 4,
"waiting": [
"accountant"
],
"prereqs_missing": 0
}
]
}
}See a module's setup#
POST/v1/platform/setup.getRead
One switched-on module's setup wizard: its steps, each with the decisions it covers (label, why it matters, Must or Should, the recommended default, the law where it is law, and the action and field that change it: call that action with dry_run to preview, then for real), who outside HR may need to look (involves), its prerequisites (met or not, and how to fix them), the progress (status, steps done) and open items. To set a module up: read this, make each decision with its action, then record it with platform.setup.update (steps_done, then finish: done). Refused for a module that is off or has no wizard yet. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
platform_setup_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
modulestring (enum)requiredOne of:
timeoff,timeclock,shifts,documents,assets,checkins,renewals,hiring,training,talent,insights,payroll,finance,analytics,pay_equity,comp_reviews,more_integrations,bank_verification,benefits,surveys,assistant.
Returns
13 fields
modulestring (enum)requiredOne of:
timeoff,timeclock,shifts,documents,assets,checkins,renewals,hiring,training,talent,insights,payroll,finance,analytics,pay_equity,comp_reviews,more_integrations,bank_verification,benefits,surveys,assistant.namestringrequiredpathstringrequiredThe wizard in Bizisy (Manage path).
settings_pathstringrequiredstatus"not_started" | "in_progress" | "done"requirednot_started, in_progress (some steps done), done (finished in the wizard, defaults kept by skipping, or every step done).
skippedbooleanrequiredFinished with "Skip: keep all the defaults".
steps_doneintegerrequiredsteps_totalintegerrequiredstarted_atstring | nullrequireddone_atstring | nullrequiredstepsobject[]required5 fields
idstringrequiredtitlestringrequireddonebooleanrequireddecisionsobject[]required8 fields
idstringrequiredlabelstringrequiredwhystringrequiredmustbooleanrequiredMust: the module can't work without it. Should: the recommended default works.
recommendedstringrequiredThe recommended default, in plain words.
lawstring | nullrequiredactionstringrequiredThe action that changes it (call it with dry_run first).
fieldstring | nullrequiredThe field of that action's input, when it is one.
involvesobject[]required2 fields
who"works_council" | "accountant" | "it" | "dpo" | "legal" | "managers"requiredwhystringrequired
prereqsobject[]requiredWhat the module needs before it works; the wizard fixes each in place.
5 fields
idstringrequiredlabelstringrequiredwhystringrequiredmetbooleanrequiredfixobjectrequired3 fields
kind"module" | "action"requiredmodulestring (enum)requiredOne of:
timeoff,timeclock,shifts,documents,assets,checkins,renewals,hiring,training,talent,insights,payroll,finance,analytics,pay_equity,comp_reviews,more_integrations,bank_verification,benefits,surveys.actionstring | nullrequired
open_itemsobject[]requiredPeople outside HR asked to look at a step ("Send to …"): open while resolved_at is null.
5 fields
idstringrequiredstepstringrequiredwho"works_council" | "accountant" | "it" | "dpo" | "legal" | "managers"requiredcreated_atstringrequiredresolved_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/platform/setup.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"module":"timeoff"}'const res = await fetch('https://api.bizisy.com/v1/platform/setup.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"module": "timeoff"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/platform/setup.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"module": "timeoff",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"module": "timeoff",
"name": "Time off",
"path": "/time-off/setup",
"settings_path": "/settings/time-off",
"status": "in_progress",
"skipped": false,
"steps_done": 2,
"steps_total": 4,
"started_at": "2026-11-16T09:00:00.000Z",
"done_at": null,
"steps": [
{
"id": "places",
"title": "Where and holidays",
"done": true,
"involves": [],
"decisions": [
{
"id": "holidays",
"label": "Public holidays",
"why": "Nobody spends allowance on a public holiday: each location gets its own.",
"must": true,
"recommended": "From each location’s country and region",
"law": null,
"action": "org.locations.update",
"field": "region"
},
{
"id": "company_days",
"label": "Company days off",
"why": "Days the whole company closes (such as 24 December) don’t use anyone’s allowance.",
"must": false,
"recommended": "None",
"law": null,
"action": "timeoff.holidays.set_day",
"field": null
}
]
},
{
"id": "allowance",
"title": "Allowance",
"done": true,
"involves": [
{
"who": "accountant",
"why": "A collective agreement or the contracts may give more days than the law: your accountant or labour adviser knows."
}
],
"decisions": [
{
"id": "annual_days",
"label": "Days a year",
"why": "What a full-time person may take; part-timers and joiners get their share.",
"must": false,
"recommended": "The legal minimum of each location’s country",
"law": "EU Working Time Directive 2003/88/EC, Article 7: at least four weeks of paid leave",
"action": "timeoff.policies.set",
"field": "annual_days"
},
{
"id": "carry_over",
"label": "Days not taken",
"why": "Whether unused days are lost or move to next year, so balances stay predictable.",
"must": false,
"recommended": "Up to 5 days carry over",
"law": null,
"action": "timeoff.policies.set",
"field": "carry_over"
}
]
},
{
"id": "decide",
"title": "How requests get decided",
"done": false,
"involves": [],
"decisions": [
{
"id": "approvals",
"label": "Who decides requests",
"why": "Who says yes before a booking is final, or rules that decide by themselves.",
"must": false,
"recommended": "The manager approves",
"law": null,
"action": "timeoff.settings.update",
"field": "approvals"
}
]
},
{
"id": "rules",
"title": "Starter rules",
"done": false,
"involves": [],
"decisions": [
{
"id": "starter_rules",
"label": "Booking rules",
"why": "Notice, enough people at work, no very long stretches: checked on every booking, with the reason shown.",
"must": false,
"recommended": "Notice for long holidays and no very long stretches",
"law": null,
"action": "timeoff.rules.create",
"field": null
}
]
}
],
"prereqs": [
{
"id": "location",
"label": "A location with its country",
"why": "Its country sets the public holidays and the legal minimum allowance.",
"met": true,
"fix": {
"kind": "action",
"module": null,
"action": "org.locations.create"
}
}
],
"open_items": [
{
"id": "oi1",
"step": "allowance",
"who": "accountant",
"created_at": "2026-11-16T09:05:00.000Z",
"resolved_at": null
}
]
}
}Record a module's setup progress#
POST/v1/platform/setup.updateWrite
Records progress of a switched-on module's setup (the decisions themselves are made with their own actions, named by platform.setup.get): steps_done marks steps done (ids from platform.setup.get; adds to what is done), finish: done finishes it (every step done), finish: skipped finishes it keeping all the recommended defaults. open_item.add asks someone outside HR to look at a step (who: works_council, accountant, it, dpo, legal or managers; Bizisy sends nothing: the person sends the prepared note themselves) and open_item.resolve closes one by id. At most 20 open items per module. Unknown steps, modules that are off and modules without a wizard are refused. Supports dry run. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
platform_setup_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
modulestring (enum)requiredOne of:
timeoff,timeclock,shifts,documents,assets,checkins,renewals,hiring,training,talent,insights,payroll,finance,analytics,pay_equity,comp_reviews,more_integrations,bank_verification,benefits,surveys,assistant.steps_donestring[]1–40 characters. Up to 20 items.
finish"done" | "skipped"open_itemobject2 fields (one of several shapes)
Option 1
addobjectrequired2 fields
stepstringrequired1–40 characters.
who"works_council" | "accountant" | "it" | "dpo" | "legal" | "managers"required
Option 2
resolvestringrequired1–40 characters.
Returns
13 fields
modulestring (enum)requiredOne of:
timeoff,timeclock,shifts,documents,assets,checkins,renewals,hiring,training,talent,insights,payroll,finance,analytics,pay_equity,comp_reviews,more_integrations,bank_verification,benefits,surveys,assistant.namestringrequiredpathstringrequiredThe wizard in Bizisy (Manage path).
settings_pathstringrequiredstatus"not_started" | "in_progress" | "done"requirednot_started, in_progress (some steps done), done (finished in the wizard, defaults kept by skipping, or every step done).
skippedbooleanrequiredFinished with "Skip: keep all the defaults".
steps_doneintegerrequiredsteps_totalintegerrequiredstarted_atstring | nullrequireddone_atstring | nullrequiredstepsobject[]required5 fields
idstringrequiredtitlestringrequireddonebooleanrequireddecisionsobject[]required8 fields
idstringrequiredlabelstringrequiredwhystringrequiredmustbooleanrequiredMust: the module can't work without it. Should: the recommended default works.
recommendedstringrequiredThe recommended default, in plain words.
lawstring | nullrequiredactionstringrequiredThe action that changes it (call it with dry_run first).
fieldstring | nullrequiredThe field of that action's input, when it is one.
involvesobject[]required2 fields
who"works_council" | "accountant" | "it" | "dpo" | "legal" | "managers"requiredwhystringrequired
prereqsobject[]requiredWhat the module needs before it works; the wizard fixes each in place.
5 fields
idstringrequiredlabelstringrequiredwhystringrequiredmetbooleanrequiredfixobjectrequired3 fields
kind"module" | "action"requiredmodulestring (enum)requiredOne of:
timeoff,timeclock,shifts,documents,assets,checkins,renewals,hiring,training,talent,insights,payroll,finance,analytics,pay_equity,comp_reviews,more_integrations,bank_verification,benefits,surveys.actionstring | nullrequired
open_itemsobject[]requiredPeople outside HR asked to look at a step ("Send to …"): open while resolved_at is null.
5 fields
idstringrequiredstepstringrequiredwho"works_council" | "accountant" | "it" | "dpo" | "legal" | "managers"requiredcreated_atstringrequiredresolved_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/platform/setup.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"module": "timeoff",
"open_item": {
"add": {
"step": "allowance",
"who": "accountant"
}
}
}'const res = await fetch('https://api.bizisy.com/v1/platform/setup.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"module": "timeoff",
"open_item": {
"add": {
"step": "allowance",
"who": "accountant"
}
}
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/platform/setup.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"module": "timeoff",
"open_item": {
"add": {
"step": "allowance",
"who": "accountant",
},
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"module": "timeoff",
"name": "Time off",
"path": "/time-off/setup",
"settings_path": "/settings/time-off",
"status": "in_progress",
"skipped": false,
"steps_done": 2,
"steps_total": 4,
"started_at": "2026-11-16T09:00:00.000Z",
"done_at": null,
"steps": [
{
"id": "places",
"title": "Where and holidays",
"done": true,
"involves": [],
"decisions": [
{
"id": "holidays",
"label": "Public holidays",
"why": "Nobody spends allowance on a public holiday: each location gets its own.",
"must": true,
"recommended": "From each location’s country and region",
"law": null,
"action": "org.locations.update",
"field": "region"
},
{
"id": "company_days",
"label": "Company days off",
"why": "Days the whole company closes (such as 24 December) don’t use anyone’s allowance.",
"must": false,
"recommended": "None",
"law": null,
"action": "timeoff.holidays.set_day",
"field": null
}
]
},
{
"id": "allowance",
"title": "Allowance",
"done": true,
"involves": [
{
"who": "accountant",
"why": "A collective agreement or the contracts may give more days than the law: your accountant or labour adviser knows."
}
],
"decisions": [
{
"id": "annual_days",
"label": "Days a year",
"why": "What a full-time person may take; part-timers and joiners get their share.",
"must": false,
"recommended": "The legal minimum of each location’s country",
"law": "EU Working Time Directive 2003/88/EC, Article 7: at least four weeks of paid leave",
"action": "timeoff.policies.set",
"field": "annual_days"
},
{
"id": "carry_over",
"label": "Days not taken",
"why": "Whether unused days are lost or move to next year, so balances stay predictable.",
"must": false,
"recommended": "Up to 5 days carry over",
"law": null,
"action": "timeoff.policies.set",
"field": "carry_over"
}
]
},
{
"id": "decide",
"title": "How requests get decided",
"done": false,
"involves": [],
"decisions": [
{
"id": "approvals",
"label": "Who decides requests",
"why": "Who says yes before a booking is final, or rules that decide by themselves.",
"must": false,
"recommended": "The manager approves",
"law": null,
"action": "timeoff.settings.update",
"field": "approvals"
}
]
},
{
"id": "rules",
"title": "Starter rules",
"done": false,
"involves": [],
"decisions": [
{
"id": "starter_rules",
"label": "Booking rules",
"why": "Notice, enough people at work, no very long stretches: checked on every booking, with the reason shown.",
"must": false,
"recommended": "Notice for long holidays and no very long stretches",
"law": null,
"action": "timeoff.rules.create",
"field": null
}
]
}
],
"prereqs": [
{
"id": "location",
"label": "A location with its country",
"why": "Its country sets the public holidays and the legal minimum allowance.",
"met": true,
"fix": {
"kind": "action",
"module": null,
"action": "org.locations.create"
}
}
],
"open_items": [
{
"id": "oi1",
"step": "allowance",
"who": "accountant",
"created_at": "2026-11-16T09:05:00.000Z",
"resolved_at": null
}
]
}
}Initialise the company (idempotent)#
POST/v1/org/setup.initWrite
Creates whatever is missing of: the legal entity (company name and country), a "Head office" location, the company root unit, the org settings (a new company's time off starts with the manager approving), and your own person record (job title "Founder" unless owner_title is given, starting today) linked to your login; the head office and the title are named in the company language (Sede and Fundador in Portuguese). Only owners and admins can link their own login; for anyone else the person is created and warnings asks an owner or admin to link it with platform_members_link_person. Safe to call any number of times; call it first on a new company. Returns the setup checklist plus warnings.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_setup_initon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
owner_titlestring1–120 characters.
Returns
10 fields
entitybooleanrequiredlocationbooleanrequiredunitsbooleanrequiredpeoplebooleanrequiredinvitedbooleanrequiredai_connectedbooleanrequiredtime_offboolean | nullrequiredTime off is set up (locations and holidays, allowance and approvals confirmed); null where time off is not available or switched off.
featuresbooleanrequired"Choose what you use" was saved (Settings → Modules): an optional step, not part of completed.
completedbooleanrequiredwarningsstring[]required
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/setup.init \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"owner_title":"CEO"}'const res = await fetch('https://api.bizisy.com/v1/org/setup.init', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"owner_title": "CEO"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/setup.init",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"owner_title": "CEO",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"entity": true,
"location": true,
"units": true,
"people": false,
"invited": false,
"ai_connected": false,
"time_off": false,
"features": false,
"completed": false,
"warnings": [
"Ask an owner or admin to link your login to your person record."
]
}
}Setup checklist#
POST/v1/org/setup.statusRead
Returns which setup steps are done (the same checklist as Home's "Get your company ready"): entity, location, units (more than the root), people (more than the owner), invited (at least one invite), time_off (locations and holidays, allowance and approvals confirmed in time off; null where time off is off), features (the modules choice was saved; sign-up saves it), ai_connected (a manage API key or connected AI app exists) and completed (entity, location, people, invited and time_off when it is on; teams (units) and features are optional, a company without teams is complete). Use it to decide what to do next; skill://org/get-ready walks the steps.
- Who can call it
- Manage key any Manage role
- MCP tool
org_setup_statuson HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
9 fields
entitybooleanrequiredlocationbooleanrequiredunitsbooleanrequiredpeoplebooleanrequiredinvitedbooleanrequiredai_connectedbooleanrequiredtime_offboolean | nullrequiredTime off is set up (locations and holidays, allowance and approvals confirmed); null where time off is not available or switched off.
featuresbooleanrequired"Choose what you use" was saved (Settings → Modules): an optional step, not part of completed.
completedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/setup.status \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/org/setup.status', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/setup.status",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"entity": true,
"location": true,
"units": true,
"people": false,
"invited": false,
"ai_connected": false,
"time_off": false,
"features": false,
"completed": false
}
}Set up or update the company in bulk#
POST/v1/org/setup.applyWrite
Creates or updates locations, units and people in one transaction (the fast path for setting up a whole company). At most 250 people per call: split bigger lists into batches. Matching: locations and units by name (case-insensitive), people by work_email; existing records are updated, missing ones created. People may also carry contract terms (contract_type, contract_end_date, probation_end_date, weekly_hours, notice_period_days), legal_entity (legal name), payroll details (tax_id, social_security_number, iban: refused over an API key or MCP; a change notifies the person and HR), sex (female, male, another or undisclosed, for equal-pay reporting: private, refused over an API key or MCP; null clears it), preferred_name and work_phone, personal_email, personal_phone and birthday (private: refused over an API key or MCP), fte (0–1, a job field like the contract terms) and custom: { <field key>: value } (person and job fields; job fields are written on their job like the other job columns; a person-type field takes a work email, also of someone elsewhere in the payload; a file field takes no value here: upload files with documents_field_file_start; null removes one; private fields are refused over an API key or MCP); units may carry custom too (team fields, e.g. a cost centre; private ones refused over an API key or MCP); pay is never set here (org_pay_add). A person's work_email is never changed here. units[].parent and people[].unit/location/manager_email may refer to items in the same payload, in any order. manager_email null says no manager (no default; an existing manager is cleared). A person joining or moving into a unit with no manager_email gets that unit's team lead as manager (team_lead_managers counts them; never a lead the same payload puts below them); people who stay in their unit keep their manager. Job changes of existing people take effect today (people hired today or not started yet are corrected in place); start dates of people already employed are not changed (a warning says so), nor are leavers. Everything is validated first; on validation_failed, details lists every problem with a path such as people[3].manager_email and nothing is written. Always call with dry_run=true first, show the counts and warnings to the user, and commit only after approval.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Payroll details, sex and private custom fields (of people and teams) are refused.
- MCP tool
org_setup_applyon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
locationsobject[]Up to 50 items.
5 fields
namestringrequired1–100 characters.
countryanyrequiredregionany | nullState or province code for public holidays (time off).
citystring | nullUp to 100 characters.
timezonestring
unitsobject[]Up to 200 items.
4 fields
namestringrequired1–100 characters.
kind"division" | "department" | "team"requiredparentstringParent unit name; defaults to the company root for new units.
1–100 characters.
customobjectTeam custom fields (
org_fields_list, target unit) by key; null clears one. Person fields take a work email or a person id.
peopleobject[]At most 250 people per call.
26 fields
given_namestringrequired1–100 characters.
family_namestringrequired1–100 characters.
work_emailanyrequiredtitlestringrequired1–120 characters.
unitstring1–100 characters.
manager_emailany | nullThe manager's work email; null for no manager (no team-lead default); absent: the team lead for someone joining or moving teams, else unchanged.
locationstring1–100 characters.
start_datestringemployment_type"full_time" | "part_time" | "contractor" | "intern"contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"contract_end_datestringprobation_end_datestringweekly_hoursnumberFrom 0 to 80.
notice_period_daysintegerFrom 0 to 365.
legal_entitystringLegal name of an existing legal entity (case-insensitive).
1–200 characters.
tax_idstringPattern
^[A-Za-z0-9 ./-]{1,40}$.social_security_numberstringPattern
^[A-Za-z0-9 ./-]{1,40}$.ibananysex"female" | "male" | "another" | "undisclosed"Sex for equal-pay reporting (private): refused over an API key or MCP; null clears it.
preferred_namestring | null1–100 characters.
work_phonestring | nullPattern
^\+?[0-9 ().-]{3,40}$.personal_emailany | nullPrivate: refused over an API key or MCP.
personal_phonestring | nullPrivate: refused over an API key or MCP.
Pattern
^\+?[0-9 ().-]{3,40}$.birthdaystring | nullYYYY-MM-DD. Private: refused over an API key or MCP.
ftenumberFull-time equivalent, e.g. 0.8 (a job field: changes like the other job columns).
From 0 to 1.
customobjectCustom field values by key (
org_fields_list): person fields and job fields (target job: written on their job like the other job columns); null clears one. Person-type fields take a work email (or a person id), also of someone elsewhere in this payload.
effective_datestringThe day job changes of people already employed take effect (YYYY-MM-DD, default today; the same checks as
org_people_change_job). New people start on their start_date.
Returns
createdobjectrequired3 fields
locationsintegerrequiredunitsintegerrequiredpeopleintegerrequired
updatedobjectrequired3 fields
locationsintegerrequiredunitsintegerrequiredpeopleintegerrequired
warningsstring[]requiredteam_lead_managersintegerrequiredPeople who got their team lead as manager because no manager was given (new people, and people moving teams).
titlesobject2 fields
matchedintegerrequiredDistinct titles in the payload already in the job title catalog.
addedobject[]requiredTitles the catalog does not have yet: added when applied (similar: catalog titles that look the same; consider using one).
2 fields
namestringrequiredsimilarstring[]required
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/setup.apply \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"locations": [
{
"name": "Porto",
"country": "PT",
"city": "Porto",
"timezone": "Europe/Lisbon"
},
{
"name": "Remote",
"country": "PT",
"city": null
},
{
"name": "Madrid",
"country": "ES",
"region": "MD",
"city": "Madrid"
}
],
"units": [
{
"name": "Engineering",
"kind": "department"
},
{
"name": "Platform",
"kind": "team",
"parent": "Engineering"
}
],
"people": [
{
"given_name": "Inês",
"family_name": "Martins",
"work_email": "ines@acme.test",
"title": "AE",
"unit": "Platform",
"manager_email": "ana@acme.test",
"location": "Porto",
"start_date": "2026-11-02",
"employment_type": "part_time"
}
]
}'const res = await fetch('https://api.bizisy.com/v1/org/setup.apply', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"locations": [
{
"name": "Porto",
"country": "PT",
"city": "Porto",
"timezone": "Europe/Lisbon"
},
{
"name": "Remote",
"country": "PT",
"city": null
},
{
"name": "Madrid",
"country": "ES",
"region": "MD",
"city": "Madrid"
}
],
"units": [
{
"name": "Engineering",
"kind": "department"
},
{
"name": "Platform",
"kind": "team",
"parent": "Engineering"
}
],
"people": [
{
"given_name": "Inês",
"family_name": "Martins",
"work_email": "ines@acme.test",
"title": "AE",
"unit": "Platform",
"manager_email": "ana@acme.test",
"location": "Porto",
"start_date": "2026-11-02",
"employment_type": "part_time"
}
]
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/setup.apply",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"locations": [
{
"name": "Porto",
"country": "PT",
"city": "Porto",
"timezone": "Europe/Lisbon",
},
{
"name": "Remote",
"country": "PT",
"city": None,
},
{
"name": "Madrid",
"country": "ES",
"region": "MD",
"city": "Madrid",
},
],
"units": [
{
"name": "Engineering",
"kind": "department",
},
{
"name": "Platform",
"kind": "team",
"parent": "Engineering",
},
],
"people": [
{
"given_name": "Inês",
"family_name": "Martins",
"work_email": "ines@acme.test",
"title": "AE",
"unit": "Platform",
"manager_email": "ana@acme.test",
"location": "Porto",
"start_date": "2026-11-02",
"employment_type": "part_time",
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"created": {
"locations": 0,
"units": 0,
"people": 1
},
"updated": {
"locations": 0,
"units": 0,
"people": 0
},
"warnings": [],
"team_lead_managers": 1
}
}Import people from a CSV#
POST/v1/org/people.import_csvWrite
Imports people from CSV text (comma or semicolon separated, first row = header, at most 1 MB and 250 people; split bigger files into batches). Columns, any case: given_name, family_name, work_email, title (required), team, manager_email, location, start_date (YYYY-MM-DD), employment_type (full_time, part_time, contractor, intern), contract_type (permanent, fixed_term, temporary, internship, freelance), contract_end_date and probation_end_date (YYYY-MM-DD), weekly_hours (e.g. 40 or 37,5), notice_period_days, legal_entity (legal name of an existing entity), tax_id, social_security_number, iban (payroll details: only when signed in to Bizisy, refused over an API key or MCP), sex (female, male, another or undisclosed, also f or m, any case: for equal-pay reporting, private, refused over an API key or MCP), preferred_name, work_phone, personal_email, personal_phone and birthday (YYYY-MM-DD; personal email, personal phone and birthday are private: refused over an API key or MCP), fte (e.g. 0.8 or 80%), and custom fields by their key (org_fields_list; values typed per field, select values must be one of its options; private fields are refused over an API key or MCP). Empty cells leave values unchanged, except an empty manager_email for someone new or moving to another team: the team lead of that team becomes the manager (team_lead_managers counts them); write none (or -) in manager_email for no manager. Pay is never imported (record it with org_pay_add). Teams that do not exist yet become teams under the company root; locations and legal entities must already exist. Managers may appear anywhere in the file. Rows are matched by work_email like org_setup_apply. If row_errors is not empty, nothing was applied: fix those rows (row numbers as in a spreadsheet, the header is row 1; row 0 means the whole file) and retry. Unknown columns are ignored with a warning. Use dry_run first.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Payroll details, sex and private custom fields are refused.
- MCP tool
org_people_import_csvon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
csvstringrequired1–1000000 characters.
Returns
createdobjectrequired3 fields
locationsintegerrequiredunitsintegerrequiredpeopleintegerrequired
updatedobjectrequired3 fields
locationsintegerrequiredunitsintegerrequiredpeopleintegerrequired
warningsstring[]requiredteam_lead_managersintegerrequiredPeople who got their team lead as manager because no manager was given (new people, and people moving teams).
titlesobject2 fields
matchedintegerrequiredDistinct titles in the payload already in the job title catalog.
addedobject[]requiredTitles the catalog does not have yet: added when applied (similar: catalog titles that look the same; consider using one).
2 fields
namestringrequiredsimilarstring[]required
row_errorsobject[]required2 fields
rowintegerrequiredmessagestringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/people.import_csv \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"csv": "given_name,family_name,work_email,title\nInês,Martins,ines@acme.test,AE\n"
}'const res = await fetch('https://api.bizisy.com/v1/org/people.import_csv', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"csv": "given_name,family_name,work_email,title\nInês,Martins,ines@acme.test,AE\n"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/people.import_csv",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"csv": "given_name,family_name,work_email,title\nInês,Martins,ines@acme.test,AE\n",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"created": {
"locations": 0,
"units": 0,
"people": 0
},
"updated": {
"locations": 0,
"units": 0,
"people": 0
},
"warnings": [],
"team_lead_managers": 0,
"row_errors": [
{
"row": 3,
"message": "work_email: Use a valid email address."
}
]
}
}Upload a file to import#
POST/v1/org/imports.uploadWrite
Starts the upload of a CSV file over 1 MB (at most 20 MB) for org_imports_start: PUT the bytes to upload.url with upload.headers, then call org_imports_start with file_id. Only in Bizisy.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_imports_uploadon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
namestringrequired1–200 characters.
sizeintegerrequiredFrom 0 to 20971520.
sha256stringrequiredPattern
^[0-9a-f]{64}$.
Returns
file_idstringrequireduploadobject | nullrequired4 fields
urlstringrequiredmethod"PUT"requiredheadersobjectrequiredresumablefalserequired
expires_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/imports.upload \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"name": "people.csv",
"size": 2400000,
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}'const res = await fetch('https://api.bizisy.com/v1/org/imports.upload', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"name": "people.csv",
"size": 2400000,
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/imports.upload",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"name": "people.csv",
"size": 2400000,
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"file_id": "f1",
"upload": {
"url": "https://storage.example/u",
"method": "PUT",
"headers": {
"content-type": "text/csv"
},
"resumable": false
},
"expires_at": "2026-10-09T09:15:00.000Z"
}
}Start an import of people#
POST/v1/org/imports.startWrite
Starts an import run of people from a CSV file (first row = header): csv (text, at most 1 MB) or file_id (a file uploaded with org_imports_upload, in Bizisy only). At most 10000 people; over an API key or AI app at most 250 (bigger files: in Bizisy). The run reads the file and suggests which column of the file feeds which field (status mapping; header, samples, columns, targets). Then: org_imports_check (choose or confirm columns, effective_date), org_imports_rows (what happens to each person), org_imports_apply. Files of up to 250 people are read at once; bigger ones in the background (status reading: follow with org_imports_get). Limits: one import working at a time, 20 open, 30 a day. Runs are kept 30 days.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- CSV text of at most 250 people; files are imported in the app.
- MCP tool
org_imports_starton HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
csvstring1–1000000 characters.
file_idstring1–64 characters.
namestringThe file's name, shown on the run.
Up to 200 characters.
Returns
25 fields
idstringrequiredstatusstring (enum)requiredOne of:
reading,mapping,checking,checked,applying,done,cancelled,failed.phase"reading" | "checking" | "applying"requiredThe phase at work, or the one that stopped (cancelled, failed):
org_imports_resumeruns it again.namestringrequiredsizeintegerrequiredheaderstring[]requiredsamplesstring[][]requiredThe first rows of the file, beside the columns (private columns are hidden from API keys and AI apps).
columnsstring | null[]requiredThe column each header cell feeds (null: not imported).
columns_setbooleanrequiredtargetsstring[]requiredEvery column a header cell can feed: the built-in ones and the custom fields by key.
effective_datestring | nullrequiredrows_totalintegerrequiredcountsobjectrequiredRows by outcome (rows not applied yet) and rows applied.
8 fields
newintegerrequiredupdateintegerrequiredunchangedintegerrequiredproblemintegerrequiredRows to fix.
blockedintegerrequiredRows waiting for a row to fix (their manager).
appliedintegerrequiredRows done.
addedintegerrequiredPeople added.
updatedintegerrequiredPeople changed.
progressobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
file_errorsstring[]requiredProblems with the whole file (e.g. a required column not chosen): nothing can be applied until fixed.
warningsstring[]requiredtitlesobject | nullrequiredJob titles of the rows to import: how many match the job title catalog, and the new ones (added to the catalog when applied; similar: catalog titles that look the same).
2 fields
matchedintegerrequiredaddedobject[]required2 fields
namestringrequiredsimilarstring[]required
started_byobjectrequired1 field
namestringrequired
cancel_requestedbooleanrequiredbackgroundbooleanrequiredWhether the run works on the import job (big files): follow it with
org_imports_get.errorstring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredfinished_atstring | nullrequiredexpires_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/imports.start \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"csv": "given_name,family_name,work_email,title\nInês,Martins,ines@acme.test,AE\n",
"name": "people.csv"
}'const res = await fetch('https://api.bizisy.com/v1/org/imports.start', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"csv": "given_name,family_name,work_email,title\nInês,Martins,ines@acme.test,AE\n",
"name": "people.csv"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/imports.start",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"csv": "given_name,family_name,work_email,title\nInês,Martins,ines@acme.test,AE\n",
"name": "people.csv",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "imp1",
"status": "mapping",
"phase": null,
"name": "people.csv",
"size": 2048,
"header": [
"First name",
"Last name",
"Email",
"Job title",
"Department"
],
"samples": [
[
"Inês",
"Martins",
"ines@acme.test",
"Account Executive",
"Sales"
]
],
"columns": [
"given_name",
"family_name",
"work_email",
"title",
"team"
],
"columns_set": false,
"targets": [
"given_name",
"family_name",
"work_email",
"title",
"team",
"manager_email"
],
"effective_date": null,
"rows_total": 3,
"counts": {
"new": 0,
"update": 0,
"unchanged": 0,
"problem": 0,
"blocked": 0,
"applied": 0,
"added": 0,
"updated": 0
},
"progress": {
"done": 0,
"total": 0
},
"file_errors": [],
"warnings": [],
"titles": {
"matched": 2,
"added": [
{
"name": "Account Executive",
"similar": [
"Account Manager"
]
}
]
},
"started_by": {
"name": "Marta Rocha"
},
"cancel_requested": false,
"background": false,
"error": null,
"created_at": "2026-10-09T09:00:00.000Z",
"updated_at": "2026-10-09T09:01:00.000Z",
"finished_at": null,
"expires_at": "2026-11-08T09:00:00.000Z"
}
}Check an import#
POST/v1/org/imports.checkWrite
Sets which column of the file feeds which field (columns: one entry per header cell, a target from the run's targets or null to leave it out; default: the suggested ones) and the effective_date of job changes for people already employed (YYYY-MM-DD, default today), then checks every row not applied yet against the company: new, update (with before → after), unchanged, problem (with the column and message) or blocked (waits for a row to fix: its manager). Up to 250 rows are checked at once (status checked); more in the background (status checking). Payroll details, sex and private fields are refused over an API key or AI assistant, which may also only check runs it started. Then org_imports_rows and org_imports_apply.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Payroll details, sex and private custom fields are refused; only runs the key or app started.
- MCP tool
org_imports_checkon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
import_idstringrequired1–64 characters.
columnsstring | null[]Up to 64 characters. Up to 500 items.
effective_datestring | null
Returns
25 fields
idstringrequiredstatusstring (enum)requiredOne of:
reading,mapping,checking,checked,applying,done,cancelled,failed.phase"reading" | "checking" | "applying"requiredThe phase at work, or the one that stopped (cancelled, failed):
org_imports_resumeruns it again.namestringrequiredsizeintegerrequiredheaderstring[]requiredsamplesstring[][]requiredThe first rows of the file, beside the columns (private columns are hidden from API keys and AI apps).
columnsstring | null[]requiredThe column each header cell feeds (null: not imported).
columns_setbooleanrequiredtargetsstring[]requiredEvery column a header cell can feed: the built-in ones and the custom fields by key.
effective_datestring | nullrequiredrows_totalintegerrequiredcountsobjectrequiredRows by outcome (rows not applied yet) and rows applied.
8 fields
newintegerrequiredupdateintegerrequiredunchangedintegerrequiredproblemintegerrequiredRows to fix.
blockedintegerrequiredRows waiting for a row to fix (their manager).
appliedintegerrequiredRows done.
addedintegerrequiredPeople added.
updatedintegerrequiredPeople changed.
progressobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
file_errorsstring[]requiredProblems with the whole file (e.g. a required column not chosen): nothing can be applied until fixed.
warningsstring[]requiredtitlesobject | nullrequiredJob titles of the rows to import: how many match the job title catalog, and the new ones (added to the catalog when applied; similar: catalog titles that look the same).
2 fields
matchedintegerrequiredaddedobject[]required2 fields
namestringrequiredsimilarstring[]required
started_byobjectrequired1 field
namestringrequired
cancel_requestedbooleanrequiredbackgroundbooleanrequiredWhether the run works on the import job (big files): follow it with
org_imports_get.errorstring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredfinished_atstring | nullrequiredexpires_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/imports.check \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"import_id": "imp1",
"columns": [
"given_name",
"family_name",
"work_email",
"title",
null
],
"effective_date": "2026-11-01"
}'const res = await fetch('https://api.bizisy.com/v1/org/imports.check', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"import_id": "imp1",
"columns": [
"given_name",
"family_name",
"work_email",
"title",
null
],
"effective_date": "2026-11-01"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/imports.check",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"import_id": "imp1",
"columns": [
"given_name",
"family_name",
"work_email",
"title",
None,
],
"effective_date": "2026-11-01",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "imp1",
"status": "checked",
"phase": null,
"name": "people.csv",
"size": 2048,
"header": [
"First name",
"Last name",
"Email",
"Job title",
"Department"
],
"samples": [
[
"Inês",
"Martins",
"ines@acme.test",
"Account Executive",
"Sales"
]
],
"columns": [
"given_name",
"family_name",
"work_email",
"title",
"team"
],
"columns_set": true,
"targets": [
"given_name",
"family_name",
"work_email",
"title",
"team",
"manager_email"
],
"effective_date": "2026-11-01",
"rows_total": 3,
"counts": {
"new": 1,
"update": 1,
"unchanged": 0,
"problem": 1,
"blocked": 0,
"applied": 0,
"added": 0,
"updated": 0
},
"progress": {
"done": 0,
"total": 0
},
"file_errors": [],
"warnings": [],
"titles": {
"matched": 2,
"added": [
{
"name": "Account Executive",
"similar": [
"Account Manager"
]
}
]
},
"started_by": {
"name": "Marta Rocha"
},
"cancel_requested": false,
"background": false,
"error": null,
"created_at": "2026-10-09T09:00:00.000Z",
"updated_at": "2026-10-09T09:01:00.000Z",
"finished_at": null,
"expires_at": "2026-11-08T09:00:00.000Z"
}
}Get an import#
POST/v1/org/imports.getRead
One import run: status (reading, mapping, checking, checked, applying, done, cancelled, failed), columns, counts by outcome, progress, problems with the whole file and warnings. Follow a run in the background with this. Payroll, sex and private cells of the sample rows are hidden from an API key or AI assistant.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Payroll, sex and private cells of the sample rows are hidden.
- MCP tool
org_imports_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
import_idstringrequired1–64 characters.
Returns
25 fields
idstringrequiredstatusstring (enum)requiredOne of:
reading,mapping,checking,checked,applying,done,cancelled,failed.phase"reading" | "checking" | "applying"requiredThe phase at work, or the one that stopped (cancelled, failed):
org_imports_resumeruns it again.namestringrequiredsizeintegerrequiredheaderstring[]requiredsamplesstring[][]requiredThe first rows of the file, beside the columns (private columns are hidden from API keys and AI apps).
columnsstring | null[]requiredThe column each header cell feeds (null: not imported).
columns_setbooleanrequiredtargetsstring[]requiredEvery column a header cell can feed: the built-in ones and the custom fields by key.
effective_datestring | nullrequiredrows_totalintegerrequiredcountsobjectrequiredRows by outcome (rows not applied yet) and rows applied.
8 fields
newintegerrequiredupdateintegerrequiredunchangedintegerrequiredproblemintegerrequiredRows to fix.
blockedintegerrequiredRows waiting for a row to fix (their manager).
appliedintegerrequiredRows done.
addedintegerrequiredPeople added.
updatedintegerrequiredPeople changed.
progressobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
file_errorsstring[]requiredProblems with the whole file (e.g. a required column not chosen): nothing can be applied until fixed.
warningsstring[]requiredtitlesobject | nullrequiredJob titles of the rows to import: how many match the job title catalog, and the new ones (added to the catalog when applied; similar: catalog titles that look the same).
2 fields
matchedintegerrequiredaddedobject[]required2 fields
namestringrequiredsimilarstring[]required
started_byobjectrequired1 field
namestringrequired
cancel_requestedbooleanrequiredbackgroundbooleanrequiredWhether the run works on the import job (big files): follow it with
org_imports_get.errorstring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredfinished_atstring | nullrequiredexpires_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/imports.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"import_id":"imp1"}'const res = await fetch('https://api.bizisy.com/v1/org/imports.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"import_id": "imp1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/imports.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"import_id": "imp1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "imp1",
"status": "checked",
"phase": null,
"name": "people.csv",
"size": 2048,
"header": [
"First name",
"Last name",
"Email",
"Job title",
"Department"
],
"samples": [
[
"Inês",
"Martins",
"ines@acme.test",
"Account Executive",
"Sales"
]
],
"columns": [
"given_name",
"family_name",
"work_email",
"title",
"team"
],
"columns_set": true,
"targets": [
"given_name",
"family_name",
"work_email",
"title",
"team",
"manager_email"
],
"effective_date": null,
"rows_total": 3,
"counts": {
"new": 1,
"update": 1,
"unchanged": 0,
"problem": 1,
"blocked": 0,
"applied": 0,
"added": 0,
"updated": 0
},
"progress": {
"done": 0,
"total": 0
},
"file_errors": [],
"warnings": [],
"titles": {
"matched": 2,
"added": [
{
"name": "Account Executive",
"similar": [
"Account Manager"
]
}
]
},
"started_by": {
"name": "Marta Rocha"
},
"cancel_requested": false,
"background": false,
"error": null,
"created_at": "2026-10-09T09:00:00.000Z",
"updated_at": "2026-10-09T09:01:00.000Z",
"finished_at": null,
"expires_at": "2026-11-08T09:00:00.000Z"
}
}List imports#
POST/v1/org/imports.listRead
The company's import runs of the last 30 days, newest first (at most 20), without sample rows.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_imports_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
An array of objects with 25 fields
An array of objects:
idstringrequiredstatusstring (enum)requiredOne of:
reading,mapping,checking,checked,applying,done,cancelled,failed.phase"reading" | "checking" | "applying"requiredThe phase at work, or the one that stopped (cancelled, failed):
org_imports_resumeruns it again.namestringrequiredsizeintegerrequiredheaderstring[]requiredsamplesstring[][]requiredThe first rows of the file, beside the columns (private columns are hidden from API keys and AI apps).
columnsstring | null[]requiredThe column each header cell feeds (null: not imported).
columns_setbooleanrequiredtargetsstring[]requiredEvery column a header cell can feed: the built-in ones and the custom fields by key.
effective_datestring | nullrequiredrows_totalintegerrequiredcountsobjectrequiredRows by outcome (rows not applied yet) and rows applied.
8 fields
newintegerrequiredupdateintegerrequiredunchangedintegerrequiredproblemintegerrequiredRows to fix.
blockedintegerrequiredRows waiting for a row to fix (their manager).
appliedintegerrequiredRows done.
addedintegerrequiredPeople added.
updatedintegerrequiredPeople changed.
progressobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
file_errorsstring[]requiredProblems with the whole file (e.g. a required column not chosen): nothing can be applied until fixed.
warningsstring[]requiredtitlesobject | nullrequiredJob titles of the rows to import: how many match the job title catalog, and the new ones (added to the catalog when applied; similar: catalog titles that look the same).
2 fields
matchedintegerrequiredaddedobject[]required2 fields
namestringrequiredsimilarstring[]required
started_byobjectrequired1 field
namestringrequired
cancel_requestedbooleanrequiredbackgroundbooleanrequiredWhether the run works on the import job (big files): follow it with
org_imports_get.errorstring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredfinished_atstring | nullrequiredexpires_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/imports.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/org/imports.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/imports.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": [
{
"id": "imp1",
"status": "checked",
"phase": null,
"name": "people.csv",
"size": 2048,
"header": [
"First name",
"Last name",
"Email",
"Job title",
"Department"
],
"samples": [],
"columns": [
"given_name",
"family_name",
"work_email",
"title",
"team"
],
"columns_set": true,
"targets": [
"given_name",
"family_name",
"work_email",
"title",
"team",
"manager_email"
],
"effective_date": null,
"rows_total": 3,
"counts": {
"new": 1,
"update": 1,
"unchanged": 0,
"problem": 1,
"blocked": 0,
"applied": 0,
"added": 0,
"updated": 0
},
"progress": {
"done": 0,
"total": 0
},
"file_errors": [],
"warnings": [],
"titles": {
"matched": 2,
"added": [
{
"name": "Account Executive",
"similar": [
"Account Manager"
]
}
]
},
"started_by": {
"name": "Marta Rocha"
},
"cancel_requested": false,
"background": false,
"error": null,
"created_at": "2026-10-09T09:00:00.000Z",
"updated_at": "2026-10-09T09:01:00.000Z",
"finished_at": null,
"expires_at": "2026-11-08T09:00:00.000Z"
}
]
}List the rows of an import#
POST/v1/org/imports.rowsRead
The rows of an import run in file order, at most 100 a page (after: the last row number of the previous page). filter: all, new, update, unchanged (not applied yet), fix (problems and blocked rows) or applied. Each row: outcome, changes (field, before, after; payroll details, sex and private fields only as hidden: true), errors (column and message), and its cells (null once applied; payroll, sex and private cells hidden from an API key or AI assistant).
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Payroll, sex and private cells are hidden.
- MCP tool
org_imports_rowson HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
import_idstringrequired1–64 characters.
filter"all" | "new" | "update" | "unchanged" | "fix" | "applied"Default
"all".afterintegerAt least 0. Default
0.limitintegerFrom 1 to 100. Default
50.
Returns
rowsobject[]required9 fields
rowintegerrequiredemailstringrequirednamestringrequiredoutcome"pending" | "new" | "update" | "unchanged" | "problem" | "blocked"requiredappliedbooleanrequiredperson_idstring | nullrequiredcellsstring[] | nullrequiredThe row as in the file, by header cell (null once applied). Private columns are hidden from API keys and AI apps.
changesobject[]required4 fields
fieldstringrequiredbeforestring | nullrequiredafterstring | nullrequiredhiddenboolean
errorsobject[]required2 fields
columnstring | nullrequiredmessagestringrequired
nextinteger | nullrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/imports.rows \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"import_id":"imp1","filter":"fix","after":40,"limit":100}'const res = await fetch('https://api.bizisy.com/v1/org/imports.rows', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"import_id": "imp1",
"filter": "fix",
"after": 40,
"limit": 100
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/imports.rows",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"import_id": "imp1",
"filter": "fix",
"after": 40,
"limit": 100,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"rows": [
{
"row": 2,
"email": "ines@acme.test",
"name": "Inês Martins",
"outcome": "new",
"applied": false,
"person_id": null,
"cells": [
"Inês",
"Martins",
"ines@acme.test",
"Account Executive",
"Sales"
],
"changes": [
{
"field": "title",
"before": null,
"after": "Account Executive"
}
],
"errors": []
},
{
"row": 3,
"email": "rui@",
"name": "Rui Lima",
"outcome": "problem",
"applied": false,
"person_id": null,
"cells": [
"Rui",
"Lima",
"rui@",
"Designer",
"Product"
],
"changes": [],
"errors": [
{
"column": "Email",
"message": "Use a valid email address."
}
]
}
],
"next": null
}
}Apply an import#
POST/v1/org/imports.applyWrite
Applies a checked import run: every row that is new or an update is written (new people hired, existing ones updated, job changes from the run's effective_date; the same rules as org_setup_apply). Rows with problems are parked to fix later (org_imports_fix_rows) and never block the rest. Up to 250 rows are applied at once (status done); more in the background in batches of 50 people (status applying, progress): cancel with org_imports_cancel. A row whose write fails is parked with the reason and the call says so: apply again to import the rest. Always org_imports_rows first and show the user what changes. An API key or AI assistant applies only runs it started.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Only runs the key or app started.
- MCP tool
org_imports_applyon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
import_idstringrequired1–64 characters.
Returns
25 fields
idstringrequiredstatusstring (enum)requiredOne of:
reading,mapping,checking,checked,applying,done,cancelled,failed.phase"reading" | "checking" | "applying"requiredThe phase at work, or the one that stopped (cancelled, failed):
org_imports_resumeruns it again.namestringrequiredsizeintegerrequiredheaderstring[]requiredsamplesstring[][]requiredThe first rows of the file, beside the columns (private columns are hidden from API keys and AI apps).
columnsstring | null[]requiredThe column each header cell feeds (null: not imported).
columns_setbooleanrequiredtargetsstring[]requiredEvery column a header cell can feed: the built-in ones and the custom fields by key.
effective_datestring | nullrequiredrows_totalintegerrequiredcountsobjectrequiredRows by outcome (rows not applied yet) and rows applied.
8 fields
newintegerrequiredupdateintegerrequiredunchangedintegerrequiredproblemintegerrequiredRows to fix.
blockedintegerrequiredRows waiting for a row to fix (their manager).
appliedintegerrequiredRows done.
addedintegerrequiredPeople added.
updatedintegerrequiredPeople changed.
progressobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
file_errorsstring[]requiredProblems with the whole file (e.g. a required column not chosen): nothing can be applied until fixed.
warningsstring[]requiredtitlesobject | nullrequiredJob titles of the rows to import: how many match the job title catalog, and the new ones (added to the catalog when applied; similar: catalog titles that look the same).
2 fields
matchedintegerrequiredaddedobject[]required2 fields
namestringrequiredsimilarstring[]required
started_byobjectrequired1 field
namestringrequired
cancel_requestedbooleanrequiredbackgroundbooleanrequiredWhether the run works on the import job (big files): follow it with
org_imports_get.errorstring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredfinished_atstring | nullrequiredexpires_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/imports.apply \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"import_id":"imp1"}'const res = await fetch('https://api.bizisy.com/v1/org/imports.apply', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"import_id": "imp1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/imports.apply",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"import_id": "imp1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "imp1",
"status": "done",
"phase": null,
"name": "people.csv",
"size": 2048,
"header": [
"First name",
"Last name",
"Email",
"Job title",
"Department"
],
"samples": [
[
"Inês",
"Martins",
"ines@acme.test",
"Account Executive",
"Sales"
]
],
"columns": [
"given_name",
"family_name",
"work_email",
"title",
"team"
],
"columns_set": true,
"targets": [
"given_name",
"family_name",
"work_email",
"title",
"team",
"manager_email"
],
"effective_date": null,
"rows_total": 3,
"counts": {
"new": 0,
"update": 0,
"unchanged": 0,
"problem": 1,
"blocked": 0,
"applied": 2,
"added": 1,
"updated": 1
},
"progress": {
"done": 0,
"total": 0
},
"file_errors": [],
"warnings": [],
"titles": {
"matched": 2,
"added": [
{
"name": "Account Executive",
"similar": [
"Account Manager"
]
}
]
},
"started_by": {
"name": "Marta Rocha"
},
"cancel_requested": false,
"background": false,
"error": null,
"created_at": "2026-10-09T09:00:00.000Z",
"updated_at": "2026-10-09T09:01:00.000Z",
"finished_at": "2026-10-09T09:02:00.000Z",
"expires_at": "2026-11-08T09:00:00.000Z"
}
}Cancel an import#
POST/v1/org/imports.cancelWrite
Stops an import that is working: while reading or checking nothing was written; while applying it stops after the current batch (people already written stay). The rest can be resumed (org_imports_resume) or discarded.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_imports_cancelon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
import_idstringrequired1–64 characters.
Returns
25 fields
idstringrequiredstatusstring (enum)requiredOne of:
reading,mapping,checking,checked,applying,done,cancelled,failed.phase"reading" | "checking" | "applying"requiredThe phase at work, or the one that stopped (cancelled, failed):
org_imports_resumeruns it again.namestringrequiredsizeintegerrequiredheaderstring[]requiredsamplesstring[][]requiredThe first rows of the file, beside the columns (private columns are hidden from API keys and AI apps).
columnsstring | null[]requiredThe column each header cell feeds (null: not imported).
columns_setbooleanrequiredtargetsstring[]requiredEvery column a header cell can feed: the built-in ones and the custom fields by key.
effective_datestring | nullrequiredrows_totalintegerrequiredcountsobjectrequiredRows by outcome (rows not applied yet) and rows applied.
8 fields
newintegerrequiredupdateintegerrequiredunchangedintegerrequiredproblemintegerrequiredRows to fix.
blockedintegerrequiredRows waiting for a row to fix (their manager).
appliedintegerrequiredRows done.
addedintegerrequiredPeople added.
updatedintegerrequiredPeople changed.
progressobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
file_errorsstring[]requiredProblems with the whole file (e.g. a required column not chosen): nothing can be applied until fixed.
warningsstring[]requiredtitlesobject | nullrequiredJob titles of the rows to import: how many match the job title catalog, and the new ones (added to the catalog when applied; similar: catalog titles that look the same).
2 fields
matchedintegerrequiredaddedobject[]required2 fields
namestringrequiredsimilarstring[]required
started_byobjectrequired1 field
namestringrequired
cancel_requestedbooleanrequiredbackgroundbooleanrequiredWhether the run works on the import job (big files): follow it with
org_imports_get.errorstring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredfinished_atstring | nullrequiredexpires_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/imports.cancel \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"import_id":"imp1"}'const res = await fetch('https://api.bizisy.com/v1/org/imports.cancel', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"import_id": "imp1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/imports.cancel",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"import_id": "imp1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "imp1",
"status": "applying",
"phase": null,
"name": "people.csv",
"size": 2048,
"header": [
"First name",
"Last name",
"Email",
"Job title",
"Department"
],
"samples": [
[
"Inês",
"Martins",
"ines@acme.test",
"Account Executive",
"Sales"
]
],
"columns": [
"given_name",
"family_name",
"work_email",
"title",
"team"
],
"columns_set": true,
"targets": [
"given_name",
"family_name",
"work_email",
"title",
"team",
"manager_email"
],
"effective_date": null,
"rows_total": 3,
"counts": {
"new": 1,
"update": 1,
"unchanged": 0,
"problem": 1,
"blocked": 0,
"applied": 0,
"added": 0,
"updated": 0
},
"progress": {
"done": 0,
"total": 0
},
"file_errors": [],
"warnings": [],
"titles": {
"matched": 2,
"added": [
{
"name": "Account Executive",
"similar": [
"Account Manager"
]
}
]
},
"started_by": {
"name": "Marta Rocha"
},
"cancel_requested": true,
"background": true,
"error": null,
"created_at": "2026-10-09T09:00:00.000Z",
"updated_at": "2026-10-09T09:01:00.000Z",
"finished_at": null,
"expires_at": "2026-11-08T09:00:00.000Z"
}
}Resume an import#
POST/v1/org/imports.resumeWrite
Runs the phase of a cancelled or failed import again (reading, checking or applying); rows already applied are never written twice.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_imports_resumeon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
import_idstringrequired1–64 characters.
Returns
25 fields
idstringrequiredstatusstring (enum)requiredOne of:
reading,mapping,checking,checked,applying,done,cancelled,failed.phase"reading" | "checking" | "applying"requiredThe phase at work, or the one that stopped (cancelled, failed):
org_imports_resumeruns it again.namestringrequiredsizeintegerrequiredheaderstring[]requiredsamplesstring[][]requiredThe first rows of the file, beside the columns (private columns are hidden from API keys and AI apps).
columnsstring | null[]requiredThe column each header cell feeds (null: not imported).
columns_setbooleanrequiredtargetsstring[]requiredEvery column a header cell can feed: the built-in ones and the custom fields by key.
effective_datestring | nullrequiredrows_totalintegerrequiredcountsobjectrequiredRows by outcome (rows not applied yet) and rows applied.
8 fields
newintegerrequiredupdateintegerrequiredunchangedintegerrequiredproblemintegerrequiredRows to fix.
blockedintegerrequiredRows waiting for a row to fix (their manager).
appliedintegerrequiredRows done.
addedintegerrequiredPeople added.
updatedintegerrequiredPeople changed.
progressobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
file_errorsstring[]requiredProblems with the whole file (e.g. a required column not chosen): nothing can be applied until fixed.
warningsstring[]requiredtitlesobject | nullrequiredJob titles of the rows to import: how many match the job title catalog, and the new ones (added to the catalog when applied; similar: catalog titles that look the same).
2 fields
matchedintegerrequiredaddedobject[]required2 fields
namestringrequiredsimilarstring[]required
started_byobjectrequired1 field
namestringrequired
cancel_requestedbooleanrequiredbackgroundbooleanrequiredWhether the run works on the import job (big files): follow it with
org_imports_get.errorstring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredfinished_atstring | nullrequiredexpires_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/imports.resume \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"import_id":"imp1"}'const res = await fetch('https://api.bizisy.com/v1/org/imports.resume', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"import_id": "imp1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/imports.resume",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"import_id": "imp1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "imp1",
"status": "applying",
"phase": "applying",
"name": "people.csv",
"size": 2048,
"header": [
"First name",
"Last name",
"Email",
"Job title",
"Department"
],
"samples": [
[
"Inês",
"Martins",
"ines@acme.test",
"Account Executive",
"Sales"
]
],
"columns": [
"given_name",
"family_name",
"work_email",
"title",
"team"
],
"columns_set": true,
"targets": [
"given_name",
"family_name",
"work_email",
"title",
"team",
"manager_email"
],
"effective_date": null,
"rows_total": 3,
"counts": {
"new": 1,
"update": 1,
"unchanged": 0,
"problem": 1,
"blocked": 0,
"applied": 0,
"added": 0,
"updated": 0
},
"progress": {
"done": 0,
"total": 0
},
"file_errors": [],
"warnings": [],
"titles": {
"matched": 2,
"added": [
{
"name": "Account Executive",
"similar": [
"Account Manager"
]
}
]
},
"started_by": {
"name": "Marta Rocha"
},
"cancel_requested": false,
"background": true,
"error": null,
"created_at": "2026-10-09T09:00:00.000Z",
"updated_at": "2026-10-09T09:01:00.000Z",
"finished_at": null,
"expires_at": "2026-11-08T09:00:00.000Z"
}
}Fix rows of an import#
POST/v1/org/imports.fix_rowsWrite
Replaces the cells of rows not applied yet (cells: one value per header cell, as in org_imports_rows), at most 100 rows a call, then checks the run again (as org_imports_check). Use it for the rows to fix after a check or an apply, then apply again. An API key or AI assistant fixes only runs it started, and its payroll, sex and private cells are kept as they were.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Only runs the key or app started; payroll, sex and private cells are kept as they were.
- MCP tool
org_imports_fix_rowson HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
import_idstringrequired1–64 characters.
rowsobject[]required1–100 items.
2 fields
rowintegerrequiredAt least 2.
cellsstring[]requiredUp to 1000 characters. Up to 500 items.
Returns
25 fields
idstringrequiredstatusstring (enum)requiredOne of:
reading,mapping,checking,checked,applying,done,cancelled,failed.phase"reading" | "checking" | "applying"requiredThe phase at work, or the one that stopped (cancelled, failed):
org_imports_resumeruns it again.namestringrequiredsizeintegerrequiredheaderstring[]requiredsamplesstring[][]requiredThe first rows of the file, beside the columns (private columns are hidden from API keys and AI apps).
columnsstring | null[]requiredThe column each header cell feeds (null: not imported).
columns_setbooleanrequiredtargetsstring[]requiredEvery column a header cell can feed: the built-in ones and the custom fields by key.
effective_datestring | nullrequiredrows_totalintegerrequiredcountsobjectrequiredRows by outcome (rows not applied yet) and rows applied.
8 fields
newintegerrequiredupdateintegerrequiredunchangedintegerrequiredproblemintegerrequiredRows to fix.
blockedintegerrequiredRows waiting for a row to fix (their manager).
appliedintegerrequiredRows done.
addedintegerrequiredPeople added.
updatedintegerrequiredPeople changed.
progressobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
file_errorsstring[]requiredProblems with the whole file (e.g. a required column not chosen): nothing can be applied until fixed.
warningsstring[]requiredtitlesobject | nullrequiredJob titles of the rows to import: how many match the job title catalog, and the new ones (added to the catalog when applied; similar: catalog titles that look the same).
2 fields
matchedintegerrequiredaddedobject[]required2 fields
namestringrequiredsimilarstring[]required
started_byobjectrequired1 field
namestringrequired
cancel_requestedbooleanrequiredbackgroundbooleanrequiredWhether the run works on the import job (big files): follow it with
org_imports_get.errorstring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredfinished_atstring | nullrequiredexpires_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/imports.fix_rows \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"import_id": "imp1",
"rows": [
{
"row": 3,
"cells": [
"Rui",
"Lima",
"rui@acme.test",
"Designer",
"Product"
]
}
]
}'const res = await fetch('https://api.bizisy.com/v1/org/imports.fix_rows', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"import_id": "imp1",
"rows": [
{
"row": 3,
"cells": [
"Rui",
"Lima",
"rui@acme.test",
"Designer",
"Product"
]
}
]
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/imports.fix_rows",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"import_id": "imp1",
"rows": [
{
"row": 3,
"cells": [
"Rui",
"Lima",
"rui@acme.test",
"Designer",
"Product",
],
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "imp1",
"status": "checked",
"phase": null,
"name": "people.csv",
"size": 2048,
"header": [
"First name",
"Last name",
"Email",
"Job title",
"Department"
],
"samples": [
[
"Inês",
"Martins",
"ines@acme.test",
"Account Executive",
"Sales"
]
],
"columns": [
"given_name",
"family_name",
"work_email",
"title",
"team"
],
"columns_set": true,
"targets": [
"given_name",
"family_name",
"work_email",
"title",
"team",
"manager_email"
],
"effective_date": null,
"rows_total": 3,
"counts": {
"new": 1,
"update": 1,
"unchanged": 0,
"problem": 1,
"blocked": 0,
"applied": 0,
"added": 0,
"updated": 0
},
"progress": {
"done": 0,
"total": 0
},
"file_errors": [],
"warnings": [],
"titles": {
"matched": 2,
"added": [
{
"name": "Account Executive",
"similar": [
"Account Manager"
]
}
]
},
"started_by": {
"name": "Marta Rocha"
},
"cancel_requested": false,
"background": false,
"error": null,
"created_at": "2026-10-09T09:00:00.000Z",
"updated_at": "2026-10-09T09:01:00.000Z",
"finished_at": null,
"expires_at": "2026-11-08T09:00:00.000Z"
}
}Discard an import#
POST/v1/org/imports.discardWrite
Deletes an import run that is not working, with its rows (people already applied stay as they are).
- Who can call it
- Manage key owner admin hr
- MCP tool
org_imports_discardon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
import_idstringrequired1–64 characters.
Returns
discardedtruerequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/imports.discard \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"import_id":"imp1"}'const res = await fetch('https://api.bizisy.com/v1/org/imports.discard', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"import_id": "imp1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/imports.discard",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"import_id": "imp1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"discarded": true
}
}Add sample data#
POST/v1/org/sandbox.sample_dataWrite
Developer sandboxes only: adds 12 fictional people in 3 teams (Engineering, Sales, People & Operations) with managers, so an app has something to read. Their addresses are @example.com (no email reaches anyone). Only while the company has no one but its first person. Owners and admins.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_sandbox_sample_dataon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
No input: send {}.
Returns
peopleintegerrequiredteamsintegerrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/sandbox.sample_data \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/org/sandbox.sample_data', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/sandbox.sample_data",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"people": 12,
"teams": 3
}
}Something missing or wrong on this page? Write to hello@bizisy.com.