API reference
Moves from another HR tool
Move a company from Personio, Factorial, Sesame HR, HiBob, BambooHR or a spreadsheet: start from an export, check it (the dry run), fix or skip rows, import, and undo within 24 hours. Over an API key: pasted CSV of up to 250 people; files, API connections, pay and private details in the web app.
20 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.
Upload an export file to move#
POST/v1/migration/uploadWrite
Starts the upload of an export file from another HR tool (CSV or Excel .xlsx, at most 20 MB) for migration_start: PUT the bytes to upload.url with upload.headers, then call migration_start with the file_id. Only in Bizisy.
- Who can call it
- Manage key owner admin hr
- MCP tool
migration_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}$.kind"csv" | "xlsx"required
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/migration/upload \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"name": "personio-people.xlsx",
"size": 48211,
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"kind": "xlsx"
}'const res = await fetch('https://api.bizisy.com/v1/migration/upload', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"name": "personio-people.xlsx",
"size": 48211,
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"kind": "xlsx"
}),
});
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/migration/upload",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"name": "personio-people.xlsx",
"size": 48211,
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"kind": "xlsx",
},
)
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/upload/f1",
"method": "PUT",
"headers": {
"content-type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
},
"resumable": false
},
"expires_at": "2026-10-12T09:15:00.000Z"
}
}Start a move from another HR tool#
POST/v1/migration/startWrite
Starts moving a company from Personio, Factorial, Sesame HR, HiBob, BambooHR, Meta4 PeopleNet or a spreadsheet (tool: personio, factorial, sesame, hibob, bamboohr, meta4 or other). Source, one of: csv (the people export as text, at most 1 MB; over an API key or AI app at most 250 people), files (file_ids from migration_upload: the people export, and optionally the time-off export as role timeoff and a job-history file as role history (one row per person and date, e.g. Meta4's movimientos); in Bizisy only), or connection: true (read the tool's API with the key connected in Integrations: Personio, Factorial, BambooHR or HiBob; in Bizisy only). The move reads the source and suggests which column feeds what (status mapping); files and API connections are read in the background (status reading: follow with migration_get). Then migration_check (the dry run), migration_items (problems), migration_fix_items, migration_import. Limits: one move working at a time, 10 open, 10 started a day; moves are kept 30 days. Owners, admins and HR, or a custom role with Setup and imports at Edit (e.g. an Implementation partner): such a role sees only the moves it started, moves from files or text only, and never pay, payroll identifiers or private details without Pay and Private details at Edit.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Pasted CSV of at most 250 people; files and API connections in Bizisy.
- MCP tool
migration_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
toolstring (enum)requiredOne of:
personio,factorial,sesame,hibob,bamboohr,meta4,other.csvstring1–1000000 characters.
filesobject[]1–3 items.
2 fields
file_idstringrequired1–64 characters.
role"people" | "timeoff" | "history"required
connectiontruenamestringUp to 200 characters.
Returns
25 fields
idstringrequiredtoolstring (enum)requiredOne of:
personio,factorial,sesame,hibob,bamboohr,meta4,other.statusstring (enum)requiredOne of:
reading,mapping,checking,checked,importing,undoing,done,cancelled,failed.phase"reading" | "checking" | "importing" | "undoing"requiredThe phase at work, or the one that stopped (cancelled, failed): migration_resume runs it again.
stepstring (enum)requiredImporting: the step at work (fields, people, history, pay, leave, balances, documents, finish).
One of:
fields,people,history,pay,leave,balances,documents,finish.sourceobjectrequired3 fields
kind"file" | "text" | "api"requiredfilesobject[]required3 fields
role"people" | "timeoff" | "history"requirednamestringrequiredsizeintegerrequired
connectorstring | nullrequired
sheetsobjectrequired3 fields
peopleobject | nullrequired4 fields
namestringrequiredrowsintegerrequiredcolumnsobject[]required4 fields
headerstringrequiredtargetstring | nullrequiredWhat the column feeds (null: not imported).
confidence"exact" | "likely" | "none"requiredexact: the tool's own name for it; likely: a usual name; none: not recognised.
samplesstring[]requiredThe first values (private columns as ••• for API keys and AI apps).
mapping_setbooleanrequired
timeoffobject | nullrequired4 fields
namestringrequiredrowsintegerrequiredcolumnsobject[]required4 fields
headerstringrequiredtargetstring | nullrequiredWhat the column feeds (null: not imported).
confidence"exact" | "likely" | "none"requiredexact: the tool's own name for it; likely: a usual name; none: not recognised.
samplesstring[]requiredThe first values (private columns as ••• for API keys and AI apps).
mapping_setbooleanrequired
historyobject | nullrequiredA job-history file: one row per person and date.
4 fields
namestringrequiredrowsintegerrequiredcolumnsobject[]required4 fields
headerstringrequiredtargetstring | nullrequiredWhat the column feeds (null: not imported).
confidence"exact" | "likely" | "none"requiredexact: the tool's own name for it; likely: a usual name; none: not recognised.
samplesstring[]requiredThe first values (private columns as ••• for API keys and AI apps).
mapping_setbooleanrequired
targetsobjectrequiredWhat a column can feed: the built-in targets, field:<key> for a custom field, new:<label> for a new text field.
3 fields
peoplestring[]requiredtimeoffstring[]requiredhistorystring[]required
scopeobjectrequired4 fields
paybooleanrequiredtimeoffbooleanrequireddocumentsbooleanrequiredhistorybooleanrequired
optionsobjectrequired8 fields
leave_typesobject[]required5 fields
sourcestringrequiredcountintegerrequiredtype_idstring | nullrequiredsuggestedbooleanrequireduses_balancebooleanrequired
entitiesobject[]requiredThe old tool's legal entities and the Bizisy legal entity each maps to.
4 fields
sourcestringrequiredcountintegerrequiredentitystring | nullrequiredThe Bizisy legal entity (legal name); null: the company's default one.
suggestedbooleanrequired
location_countrystring | nullrequiredeffective_datestring | nullrequiredpay_currencystringrequiredpay_period"year" | "month" | "hour"requiredvalue_mapsobject[]requiredCodes in the file (contract types, leaving reasons, sex…) and the Bizisy value each becomes (null: left out); suggested: Bizisy's guess, not chosen yet.
5 fields
targetstringrequiredsourcestringrequiredcountintegerrequiredvaluestring | nullrequiredsuggestedbooleanrequired
emailobjectrequiredHow people without a work email in the file get one: the company's pattern, or their personal email; null: the work email is required.
4 fields (one of several shapes)
Option 1
mode"pattern"requiredpattern"first.last" | "firstlast" | "f.last" | "first"requireddomainstringrequired
Option 2
mode"personal"required
countsobjectrequired10 fields
peopleobjectrequired7 fields
newintegerrequiredupdateintegerrequiredunchangedintegerrequiredproblemintegerrequiredblockedintegerrequiredskippedintegerrequiredleftintegerrequired
teamsintegerrequiredlocationsintegerrequiredfieldsintegerrequiredleaveobjectrequired5 fields
newintegerrequiredunchangedintegerrequiredproblemintegerrequiredskippedintegerrequireddaysnumberrequired
balancesobjectrequired4 fields
newintegerrequiredunchangedintegerrequiredproblemintegerrequiredskippedintegerrequired
documentsobjectrequired5 fields
newintegerrequiredunchangedintegerrequiredproblemintegerrequiredskippedintegerrequiredbytesnumberrequired
payintegerrequiredhistoryintegerrequiredjobsobjectrequiredRows of the job-history file: recorded with their person, to fix, left out.
3 fields
newintegerrequiredproblemintegerrequiredskippedintegerrequired
problemsintegerrequiredItems to fix or skip before importing (problems and blocked rows).
reportobjectrequired7 fields
unmappedstring[]requiredwarningsstring[]requiredteamsstring[]requiredlocationsstring[]requiredfieldsstring[]requiredblockingstring[]requiredstorageobject | nullrequired4 fields
bytesnumberrequiredincluded_bytesnumberrequiredused_bytesnumberrequiredprice_cents_per_gbnumberrequired
progressobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
resultobjectrequired14 fields
addedintegerrequiredupdatedintegerrequiredteamsintegerrequiredlocationsintegerrequiredfieldsintegerrequiredhistoryintegerrequiredpayintegerrequiredpay_waitingintegerPay sent for approval (Settings → Approval rules): it applies once another approver approves it.
Default
0.leaveintegerrequiredbalancesintegerrequireddocumentsintegerrequiredproblemsintegerrequiredpayroll_noticesintegerrequirednumbersintegerEmployee numbers set in Payroll.
Default
0.
undoobjectrequired5 fields
availablebooleanrequiredUndo can run now (within 24 hours of finishing, not undone yet).
untilstring | nullrequiredundone_atstring | nullrequiredremovedintegerrequiredkeptobject[]required3 fields
kindstringrequiredlabelstringrequiredreasonstringrequired
connectionobject | nullrequired2 fields
connectorstringrequiredremovedbooleanrequired
started_byobjectrequired1 field
namestringrequired
backgroundbooleanrequiredWhether the run works on the import job: follow it with migration_get.
cancel_requestedbooleanrequirederrorstring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredfinished_atstring | nullrequiredexpires_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/migration/start \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"tool": "personio",
"files": [
{
"file_id": "f1",
"role": "people"
},
{
"file_id": "f2",
"role": "timeoff"
}
]
}'const res = await fetch('https://api.bizisy.com/v1/migration/start', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"tool": "personio",
"files": [
{
"file_id": "f1",
"role": "people"
},
{
"file_id": "f2",
"role": "timeoff"
}
]
}),
});
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/migration/start",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"tool": "personio",
"files": [
{
"file_id": "f1",
"role": "people",
},
{
"file_id": "f2",
"role": "timeoff",
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "mv1",
"tool": "personio",
"status": "reading",
"phase": "reading",
"step": null,
"source": {
"kind": "file",
"files": [
{
"role": "people",
"name": "personio-people.xlsx",
"size": 48211
},
{
"role": "timeoff",
"name": "absences.csv",
"size": 2104
}
],
"connector": null
},
"sheets": {
"people": {
"name": "personio-people.xlsx",
"rows": 16,
"mapping_set": true,
"columns": [
{
"header": "First name",
"target": "given_name",
"confidence": "exact",
"samples": [
"Sofia",
"Lukas"
]
},
{
"header": "Email",
"target": "work_email",
"confidence": "exact",
"samples": [
"sofia.almeida@example-company.eu",
"lukas.becker@example-company.eu"
]
},
{
"header": "Cost center",
"target": null,
"confidence": "none",
"samples": [
"CC-MAN",
"CC-ENG"
]
}
]
},
"timeoff": {
"name": "absences.csv",
"rows": 9,
"mapping_set": true,
"columns": [
{
"header": "Absence type",
"target": "leave_type",
"confidence": "exact",
"samples": [
"Paid vacation"
]
}
]
},
"history": null
},
"targets": {
"people": [
"given_name",
"family_name",
"work_email",
"title"
],
"timeoff": [
"person_email",
"leave_type",
"start",
"end"
],
"history": [
"person_id",
"from",
"title"
]
},
"scope": {
"pay": false,
"timeoff": true,
"documents": false,
"history": true
},
"options": {
"leave_types": [
{
"source": "Paid vacation",
"count": 7,
"type_id": "vacation",
"suggested": true,
"uses_balance": true
},
{
"source": "Sick leave",
"count": 2,
"type_id": null,
"suggested": false,
"uses_balance": false
}
],
"entities": [
{
"source": "Example Company GmbH",
"count": 7,
"entity": "Acme GmbH",
"suggested": true
}
],
"location_country": "PT",
"effective_date": null,
"pay_currency": "EUR",
"pay_period": "year",
"value_maps": [
{
"target": "contract_type",
"source": "CT02",
"count": 9,
"value": "fixed_term",
"suggested": false
}
],
"email": null
},
"counts": {
"people": {
"new": 12,
"update": 1,
"unchanged": 0,
"problem": 2,
"blocked": 0,
"skipped": 0,
"left": 1
},
"teams": 4,
"locations": 2,
"fields": 1,
"leave": {
"new": 9,
"unchanged": 0,
"problem": 0,
"skipped": 0,
"days": 63.5
},
"balances": {
"new": 15,
"unchanged": 0,
"problem": 0,
"skipped": 0
},
"documents": {
"new": 0,
"unchanged": 0,
"problem": 0,
"skipped": 0,
"bytes": 0
},
"pay": 0,
"history": 0,
"jobs": {
"new": 0,
"problem": 0,
"skipped": 0
}
},
"problems": 2,
"report": {
"unmapped": [
"Cost center"
],
"warnings": [
"1 column is not imported: Cost center."
],
"teams": [
"Engineering",
"People"
],
"locations": [
"Berlin"
],
"fields": [
"Shirt size"
],
"blocking": [],
"storage": null
},
"progress": {
"done": 0,
"total": 0
},
"result": {
"added": 0,
"updated": 0,
"teams": 0,
"locations": 0,
"fields": 0,
"history": 0,
"pay": 0,
"pay_waiting": 0,
"leave": 0,
"balances": 0,
"documents": 0,
"problems": 0,
"payroll_notices": 0,
"numbers": 0
},
"undo": {
"available": false,
"until": null,
"undone_at": null,
"removed": 0,
"kept": []
},
"connection": null,
"started_by": {
"name": "Ana Ferreira"
},
"background": true,
"cancel_requested": false,
"error": null,
"created_at": "2026-10-12T09:00:00.000Z",
"updated_at": "2026-10-12T09:04:00.000Z",
"finished_at": null,
"expires_at": "2026-11-11T09:00:00.000Z"
}
}Check a move (dry run)#
POST/v1/migration/checkWrite
Sets what each column feeds (people_mapping, timeoff_mapping), what moves (scope), the leave types and options, then checks everything against the company without writing anything: each person new, update (before → after), unchanged, problem (the column and how to fix it), blocked (waits for their manager's row) or skipped (already left, invited and waiting); teams, locations and fields it would create; leave and balances; documents and the storage they need. Moves of up to 300 rows are checked at once (status checked); bigger ones and API sources in the background (status checking). counts and report sum it up ("142 people, 12 teams, 3 problems"). Payroll identifiers, sex, private details and pay are refused over an API key or AI app, which may only check moves it started. Then migration_items (filter fix) and migration_import.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Pay, payroll identifiers, sex and private details are refused; only moves the key started.
- MCP tool
migration_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
run_idstringrequired1–64 characters.
people_mappingstring | null[]One entry per column of the people file: a target from targets.people, field:<key>, new:<label>, or null to leave it out. Default: the suggested mapping.
Up to 80 characters. Up to 300 items.
timeoff_mappingstring | null[]The same for the time-off file (targets.timeoff).
Up to 80 characters. Up to 300 items.
history_mappingstring | null[]The same for the job-history file (targets.history).
Up to 80 characters. Up to 300 items.
value_mapsobject[]The Bizisy value for each code of the file (options.value_maps: contract_type, employment_type, sex, end_reason), or null to leave it out.
Up to 200 items.
3 fields
target"contract_type" | "employment_type" | "sex" | "end_reason"requiredsourcestringrequiredUp to 100 characters.
valuestring | nullrequiredUp to 40 characters.
emailobjectPeople without a work email in the file: make one with the company's pattern (first.last@domain…), or use their personal email to sign in; null: the work email is required.
4 fields (one of several shapes)
Option 1
mode"pattern"requiredpattern"first.last" | "firstlast" | "f.last" | "first"requireddomainstringrequiredUp to 200 characters.
Option 2
mode"personal"required
scopeobjectpay (default false; in Bizisy only), time off and documents (default true).
3 fields
paybooleantimeoffbooleandocumentsboolean
leave_typesobject[]The Bizisy leave type for each type of the old tool (options.leave_types), or null to leave that type out.
Up to 100 items.
2 fields
sourcestringrequiredUp to 60 characters.
type_idstring | nullrequiredUp to 60 characters.
entitiesobject[]The Bizisy legal entity (legal name) for each legal entity of the old tool (options.entities), or null for the company's default one.
Up to 50 items.
2 fields
sourcestringrequiredUp to 200 characters.
entitystring | nullrequiredUp to 200 characters.
location_countrystring | nullThe country of locations the move creates (default the company's).
Pattern
^[A-Z]{2}$.effective_datestring | nullThe day job changes of people already in Bizisy take effect (default today).
Pattern
^\d{4}-\d{2}-\d{2}$.pay_currencystringPattern
^[A-Z]{3}$.pay_period"year" | "month" | "hour"
Returns
25 fields
idstringrequiredtoolstring (enum)requiredOne of:
personio,factorial,sesame,hibob,bamboohr,meta4,other.statusstring (enum)requiredOne of:
reading,mapping,checking,checked,importing,undoing,done,cancelled,failed.phase"reading" | "checking" | "importing" | "undoing"requiredThe phase at work, or the one that stopped (cancelled, failed): migration_resume runs it again.
stepstring (enum)requiredImporting: the step at work (fields, people, history, pay, leave, balances, documents, finish).
One of:
fields,people,history,pay,leave,balances,documents,finish.sourceobjectrequired3 fields
kind"file" | "text" | "api"requiredfilesobject[]required3 fields
role"people" | "timeoff" | "history"requirednamestringrequiredsizeintegerrequired
connectorstring | nullrequired
sheetsobjectrequired3 fields
peopleobject | nullrequired4 fields
namestringrequiredrowsintegerrequiredcolumnsobject[]required4 fields
headerstringrequiredtargetstring | nullrequiredWhat the column feeds (null: not imported).
confidence"exact" | "likely" | "none"requiredexact: the tool's own name for it; likely: a usual name; none: not recognised.
samplesstring[]requiredThe first values (private columns as ••• for API keys and AI apps).
mapping_setbooleanrequired
timeoffobject | nullrequired4 fields
namestringrequiredrowsintegerrequiredcolumnsobject[]required4 fields
headerstringrequiredtargetstring | nullrequiredWhat the column feeds (null: not imported).
confidence"exact" | "likely" | "none"requiredexact: the tool's own name for it; likely: a usual name; none: not recognised.
samplesstring[]requiredThe first values (private columns as ••• for API keys and AI apps).
mapping_setbooleanrequired
historyobject | nullrequiredA job-history file: one row per person and date.
4 fields
namestringrequiredrowsintegerrequiredcolumnsobject[]required4 fields
headerstringrequiredtargetstring | nullrequiredWhat the column feeds (null: not imported).
confidence"exact" | "likely" | "none"requiredexact: the tool's own name for it; likely: a usual name; none: not recognised.
samplesstring[]requiredThe first values (private columns as ••• for API keys and AI apps).
mapping_setbooleanrequired
targetsobjectrequiredWhat a column can feed: the built-in targets, field:<key> for a custom field, new:<label> for a new text field.
3 fields
peoplestring[]requiredtimeoffstring[]requiredhistorystring[]required
scopeobjectrequired4 fields
paybooleanrequiredtimeoffbooleanrequireddocumentsbooleanrequiredhistorybooleanrequired
optionsobjectrequired8 fields
leave_typesobject[]required5 fields
sourcestringrequiredcountintegerrequiredtype_idstring | nullrequiredsuggestedbooleanrequireduses_balancebooleanrequired
entitiesobject[]requiredThe old tool's legal entities and the Bizisy legal entity each maps to.
4 fields
sourcestringrequiredcountintegerrequiredentitystring | nullrequiredThe Bizisy legal entity (legal name); null: the company's default one.
suggestedbooleanrequired
location_countrystring | nullrequiredeffective_datestring | nullrequiredpay_currencystringrequiredpay_period"year" | "month" | "hour"requiredvalue_mapsobject[]requiredCodes in the file (contract types, leaving reasons, sex…) and the Bizisy value each becomes (null: left out); suggested: Bizisy's guess, not chosen yet.
5 fields
targetstringrequiredsourcestringrequiredcountintegerrequiredvaluestring | nullrequiredsuggestedbooleanrequired
emailobjectrequiredHow people without a work email in the file get one: the company's pattern, or their personal email; null: the work email is required.
4 fields (one of several shapes)
Option 1
mode"pattern"requiredpattern"first.last" | "firstlast" | "f.last" | "first"requireddomainstringrequired
Option 2
mode"personal"required
countsobjectrequired10 fields
peopleobjectrequired7 fields
newintegerrequiredupdateintegerrequiredunchangedintegerrequiredproblemintegerrequiredblockedintegerrequiredskippedintegerrequiredleftintegerrequired
teamsintegerrequiredlocationsintegerrequiredfieldsintegerrequiredleaveobjectrequired5 fields
newintegerrequiredunchangedintegerrequiredproblemintegerrequiredskippedintegerrequireddaysnumberrequired
balancesobjectrequired4 fields
newintegerrequiredunchangedintegerrequiredproblemintegerrequiredskippedintegerrequired
documentsobjectrequired5 fields
newintegerrequiredunchangedintegerrequiredproblemintegerrequiredskippedintegerrequiredbytesnumberrequired
payintegerrequiredhistoryintegerrequiredjobsobjectrequiredRows of the job-history file: recorded with their person, to fix, left out.
3 fields
newintegerrequiredproblemintegerrequiredskippedintegerrequired
problemsintegerrequiredItems to fix or skip before importing (problems and blocked rows).
reportobjectrequired7 fields
unmappedstring[]requiredwarningsstring[]requiredteamsstring[]requiredlocationsstring[]requiredfieldsstring[]requiredblockingstring[]requiredstorageobject | nullrequired4 fields
bytesnumberrequiredincluded_bytesnumberrequiredused_bytesnumberrequiredprice_cents_per_gbnumberrequired
progressobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
resultobjectrequired14 fields
addedintegerrequiredupdatedintegerrequiredteamsintegerrequiredlocationsintegerrequiredfieldsintegerrequiredhistoryintegerrequiredpayintegerrequiredpay_waitingintegerPay sent for approval (Settings → Approval rules): it applies once another approver approves it.
Default
0.leaveintegerrequiredbalancesintegerrequireddocumentsintegerrequiredproblemsintegerrequiredpayroll_noticesintegerrequirednumbersintegerEmployee numbers set in Payroll.
Default
0.
undoobjectrequired5 fields
availablebooleanrequiredUndo can run now (within 24 hours of finishing, not undone yet).
untilstring | nullrequiredundone_atstring | nullrequiredremovedintegerrequiredkeptobject[]required3 fields
kindstringrequiredlabelstringrequiredreasonstringrequired
connectionobject | nullrequired2 fields
connectorstringrequiredremovedbooleanrequired
started_byobjectrequired1 field
namestringrequired
backgroundbooleanrequiredWhether the run works on the import job: follow it with migration_get.
cancel_requestedbooleanrequirederrorstring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredfinished_atstring | nullrequiredexpires_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/migration/check \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"run_id": "mv1",
"people_mapping": [
"given_name",
"work_email",
null
],
"timeoff_mapping": [
"leave_type"
],
"scope": {
"pay": true,
"timeoff": true,
"documents": false
},
"leave_types": [
{
"source": "Sick leave",
"type_id": null
}
],
"entities": [
{
"source": "Example Company GmbH",
"entity": null
}
],
"location_country": "DE",
"effective_date": "2026-10-12",
"pay_currency": "EUR",
"pay_period": "year"
}'const res = await fetch('https://api.bizisy.com/v1/migration/check', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"run_id": "mv1",
"people_mapping": [
"given_name",
"work_email",
null
],
"timeoff_mapping": [
"leave_type"
],
"scope": {
"pay": true,
"timeoff": true,
"documents": false
},
"leave_types": [
{
"source": "Sick leave",
"type_id": null
}
],
"entities": [
{
"source": "Example Company GmbH",
"entity": null
}
],
"location_country": "DE",
"effective_date": "2026-10-12",
"pay_currency": "EUR",
"pay_period": "year"
}),
});
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/migration/check",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"run_id": "mv1",
"people_mapping": [
"given_name",
"work_email",
None,
],
"timeoff_mapping": [
"leave_type",
],
"scope": {
"pay": True,
"timeoff": True,
"documents": False,
},
"leave_types": [
{
"source": "Sick leave",
"type_id": None,
},
],
"entities": [
{
"source": "Example Company GmbH",
"entity": None,
},
],
"location_country": "DE",
"effective_date": "2026-10-12",
"pay_currency": "EUR",
"pay_period": "year",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "mv1",
"tool": "personio",
"status": "checked",
"phase": null,
"step": null,
"source": {
"kind": "file",
"files": [
{
"role": "people",
"name": "personio-people.xlsx",
"size": 48211
},
{
"role": "timeoff",
"name": "absences.csv",
"size": 2104
}
],
"connector": null
},
"sheets": {
"people": {
"name": "personio-people.xlsx",
"rows": 16,
"mapping_set": true,
"columns": [
{
"header": "First name",
"target": "given_name",
"confidence": "exact",
"samples": [
"Sofia",
"Lukas"
]
},
{
"header": "Email",
"target": "work_email",
"confidence": "exact",
"samples": [
"sofia.almeida@example-company.eu",
"lukas.becker@example-company.eu"
]
},
{
"header": "Cost center",
"target": null,
"confidence": "none",
"samples": [
"CC-MAN",
"CC-ENG"
]
}
]
},
"timeoff": {
"name": "absences.csv",
"rows": 9,
"mapping_set": true,
"columns": [
{
"header": "Absence type",
"target": "leave_type",
"confidence": "exact",
"samples": [
"Paid vacation"
]
}
]
},
"history": null
},
"targets": {
"people": [
"given_name",
"family_name",
"work_email",
"title"
],
"timeoff": [
"person_email",
"leave_type",
"start",
"end"
],
"history": [
"person_id",
"from",
"title"
]
},
"scope": {
"pay": false,
"timeoff": true,
"documents": false,
"history": true
},
"options": {
"leave_types": [
{
"source": "Paid vacation",
"count": 7,
"type_id": "vacation",
"suggested": true,
"uses_balance": true
},
{
"source": "Sick leave",
"count": 2,
"type_id": null,
"suggested": false,
"uses_balance": false
}
],
"entities": [
{
"source": "Example Company GmbH",
"count": 7,
"entity": "Acme GmbH",
"suggested": true
}
],
"location_country": "PT",
"effective_date": null,
"pay_currency": "EUR",
"pay_period": "year",
"value_maps": [
{
"target": "contract_type",
"source": "CT02",
"count": 9,
"value": "fixed_term",
"suggested": false
}
],
"email": null
},
"counts": {
"people": {
"new": 12,
"update": 1,
"unchanged": 0,
"problem": 2,
"blocked": 0,
"skipped": 0,
"left": 1
},
"teams": 4,
"locations": 2,
"fields": 1,
"leave": {
"new": 9,
"unchanged": 0,
"problem": 0,
"skipped": 0,
"days": 63.5
},
"balances": {
"new": 15,
"unchanged": 0,
"problem": 0,
"skipped": 0
},
"documents": {
"new": 0,
"unchanged": 0,
"problem": 0,
"skipped": 0,
"bytes": 0
},
"pay": 0,
"history": 0,
"jobs": {
"new": 0,
"problem": 0,
"skipped": 0
}
},
"problems": 2,
"report": {
"unmapped": [
"Cost center"
],
"warnings": [
"1 column is not imported: Cost center."
],
"teams": [
"Engineering",
"People"
],
"locations": [
"Berlin"
],
"fields": [
"Shirt size"
],
"blocking": [],
"storage": null
},
"progress": {
"done": 0,
"total": 0
},
"result": {
"added": 0,
"updated": 0,
"teams": 0,
"locations": 0,
"fields": 0,
"history": 0,
"pay": 0,
"pay_waiting": 0,
"leave": 0,
"balances": 0,
"documents": 0,
"problems": 0,
"payroll_notices": 0,
"numbers": 0
},
"undo": {
"available": false,
"until": null,
"undone_at": null,
"removed": 0,
"kept": []
},
"connection": null,
"started_by": {
"name": "Ana Ferreira"
},
"background": true,
"cancel_requested": false,
"error": null,
"created_at": "2026-10-12T09:00:00.000Z",
"updated_at": "2026-10-12T09:04:00.000Z",
"finished_at": null,
"expires_at": "2026-11-11T09:00:00.000Z"
}
}Get a move#
POST/v1/migration/getRead
One move: status (reading, mapping, checking, checked, importing, undoing, done, cancelled, failed), the columns of each file with what they feed and the confidence, the dry run's counts and report (problems, new teams, locations and fields, leave types to map, storage), progress, the import's result and whether undo is still possible. Private and pay sample values are hidden from an API key or AI app.
- Who can call it
- Manage key owner admin hr
- MCP tool
migration_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
run_idstringrequired1–64 characters.
Returns
25 fields
idstringrequiredtoolstring (enum)requiredOne of:
personio,factorial,sesame,hibob,bamboohr,meta4,other.statusstring (enum)requiredOne of:
reading,mapping,checking,checked,importing,undoing,done,cancelled,failed.phase"reading" | "checking" | "importing" | "undoing"requiredThe phase at work, or the one that stopped (cancelled, failed): migration_resume runs it again.
stepstring (enum)requiredImporting: the step at work (fields, people, history, pay, leave, balances, documents, finish).
One of:
fields,people,history,pay,leave,balances,documents,finish.sourceobjectrequired3 fields
kind"file" | "text" | "api"requiredfilesobject[]required3 fields
role"people" | "timeoff" | "history"requirednamestringrequiredsizeintegerrequired
connectorstring | nullrequired
sheetsobjectrequired3 fields
peopleobject | nullrequired4 fields
namestringrequiredrowsintegerrequiredcolumnsobject[]required4 fields
headerstringrequiredtargetstring | nullrequiredWhat the column feeds (null: not imported).
confidence"exact" | "likely" | "none"requiredexact: the tool's own name for it; likely: a usual name; none: not recognised.
samplesstring[]requiredThe first values (private columns as ••• for API keys and AI apps).
mapping_setbooleanrequired
timeoffobject | nullrequired4 fields
namestringrequiredrowsintegerrequiredcolumnsobject[]required4 fields
headerstringrequiredtargetstring | nullrequiredWhat the column feeds (null: not imported).
confidence"exact" | "likely" | "none"requiredexact: the tool's own name for it; likely: a usual name; none: not recognised.
samplesstring[]requiredThe first values (private columns as ••• for API keys and AI apps).
mapping_setbooleanrequired
historyobject | nullrequiredA job-history file: one row per person and date.
4 fields
namestringrequiredrowsintegerrequiredcolumnsobject[]required4 fields
headerstringrequiredtargetstring | nullrequiredWhat the column feeds (null: not imported).
confidence"exact" | "likely" | "none"requiredexact: the tool's own name for it; likely: a usual name; none: not recognised.
samplesstring[]requiredThe first values (private columns as ••• for API keys and AI apps).
mapping_setbooleanrequired
targetsobjectrequiredWhat a column can feed: the built-in targets, field:<key> for a custom field, new:<label> for a new text field.
3 fields
peoplestring[]requiredtimeoffstring[]requiredhistorystring[]required
scopeobjectrequired4 fields
paybooleanrequiredtimeoffbooleanrequireddocumentsbooleanrequiredhistorybooleanrequired
optionsobjectrequired8 fields
leave_typesobject[]required5 fields
sourcestringrequiredcountintegerrequiredtype_idstring | nullrequiredsuggestedbooleanrequireduses_balancebooleanrequired
entitiesobject[]requiredThe old tool's legal entities and the Bizisy legal entity each maps to.
4 fields
sourcestringrequiredcountintegerrequiredentitystring | nullrequiredThe Bizisy legal entity (legal name); null: the company's default one.
suggestedbooleanrequired
location_countrystring | nullrequiredeffective_datestring | nullrequiredpay_currencystringrequiredpay_period"year" | "month" | "hour"requiredvalue_mapsobject[]requiredCodes in the file (contract types, leaving reasons, sex…) and the Bizisy value each becomes (null: left out); suggested: Bizisy's guess, not chosen yet.
5 fields
targetstringrequiredsourcestringrequiredcountintegerrequiredvaluestring | nullrequiredsuggestedbooleanrequired
emailobjectrequiredHow people without a work email in the file get one: the company's pattern, or their personal email; null: the work email is required.
4 fields (one of several shapes)
Option 1
mode"pattern"requiredpattern"first.last" | "firstlast" | "f.last" | "first"requireddomainstringrequired
Option 2
mode"personal"required
countsobjectrequired10 fields
peopleobjectrequired7 fields
newintegerrequiredupdateintegerrequiredunchangedintegerrequiredproblemintegerrequiredblockedintegerrequiredskippedintegerrequiredleftintegerrequired
teamsintegerrequiredlocationsintegerrequiredfieldsintegerrequiredleaveobjectrequired5 fields
newintegerrequiredunchangedintegerrequiredproblemintegerrequiredskippedintegerrequireddaysnumberrequired
balancesobjectrequired4 fields
newintegerrequiredunchangedintegerrequiredproblemintegerrequiredskippedintegerrequired
documentsobjectrequired5 fields
newintegerrequiredunchangedintegerrequiredproblemintegerrequiredskippedintegerrequiredbytesnumberrequired
payintegerrequiredhistoryintegerrequiredjobsobjectrequiredRows of the job-history file: recorded with their person, to fix, left out.
3 fields
newintegerrequiredproblemintegerrequiredskippedintegerrequired
problemsintegerrequiredItems to fix or skip before importing (problems and blocked rows).
reportobjectrequired7 fields
unmappedstring[]requiredwarningsstring[]requiredteamsstring[]requiredlocationsstring[]requiredfieldsstring[]requiredblockingstring[]requiredstorageobject | nullrequired4 fields
bytesnumberrequiredincluded_bytesnumberrequiredused_bytesnumberrequiredprice_cents_per_gbnumberrequired
progressobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
resultobjectrequired14 fields
addedintegerrequiredupdatedintegerrequiredteamsintegerrequiredlocationsintegerrequiredfieldsintegerrequiredhistoryintegerrequiredpayintegerrequiredpay_waitingintegerPay sent for approval (Settings → Approval rules): it applies once another approver approves it.
Default
0.leaveintegerrequiredbalancesintegerrequireddocumentsintegerrequiredproblemsintegerrequiredpayroll_noticesintegerrequirednumbersintegerEmployee numbers set in Payroll.
Default
0.
undoobjectrequired5 fields
availablebooleanrequiredUndo can run now (within 24 hours of finishing, not undone yet).
untilstring | nullrequiredundone_atstring | nullrequiredremovedintegerrequiredkeptobject[]required3 fields
kindstringrequiredlabelstringrequiredreasonstringrequired
connectionobject | nullrequired2 fields
connectorstringrequiredremovedbooleanrequired
started_byobjectrequired1 field
namestringrequired
backgroundbooleanrequiredWhether the run works on the import job: follow it with migration_get.
cancel_requestedbooleanrequirederrorstring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredfinished_atstring | nullrequiredexpires_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/migration/get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"run_id":"mv1"}'const res = await fetch('https://api.bizisy.com/v1/migration/get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"run_id": "mv1"
}),
});
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/migration/get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"run_id": "mv1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "mv1",
"tool": "personio",
"status": "checked",
"phase": null,
"step": null,
"source": {
"kind": "file",
"files": [
{
"role": "people",
"name": "personio-people.xlsx",
"size": 48211
},
{
"role": "timeoff",
"name": "absences.csv",
"size": 2104
}
],
"connector": null
},
"sheets": {
"people": {
"name": "personio-people.xlsx",
"rows": 16,
"mapping_set": true,
"columns": [
{
"header": "First name",
"target": "given_name",
"confidence": "exact",
"samples": [
"Sofia",
"Lukas"
]
},
{
"header": "Email",
"target": "work_email",
"confidence": "exact",
"samples": [
"sofia.almeida@example-company.eu",
"lukas.becker@example-company.eu"
]
},
{
"header": "Cost center",
"target": null,
"confidence": "none",
"samples": [
"CC-MAN",
"CC-ENG"
]
}
]
},
"timeoff": {
"name": "absences.csv",
"rows": 9,
"mapping_set": true,
"columns": [
{
"header": "Absence type",
"target": "leave_type",
"confidence": "exact",
"samples": [
"Paid vacation"
]
}
]
},
"history": null
},
"targets": {
"people": [
"given_name",
"family_name",
"work_email",
"title"
],
"timeoff": [
"person_email",
"leave_type",
"start",
"end"
],
"history": [
"person_id",
"from",
"title"
]
},
"scope": {
"pay": false,
"timeoff": true,
"documents": false,
"history": true
},
"options": {
"leave_types": [
{
"source": "Paid vacation",
"count": 7,
"type_id": "vacation",
"suggested": true,
"uses_balance": true
},
{
"source": "Sick leave",
"count": 2,
"type_id": null,
"suggested": false,
"uses_balance": false
}
],
"entities": [
{
"source": "Example Company GmbH",
"count": 7,
"entity": "Acme GmbH",
"suggested": true
}
],
"location_country": "PT",
"effective_date": null,
"pay_currency": "EUR",
"pay_period": "year",
"value_maps": [
{
"target": "contract_type",
"source": "CT02",
"count": 9,
"value": "fixed_term",
"suggested": false
}
],
"email": null
},
"counts": {
"people": {
"new": 12,
"update": 1,
"unchanged": 0,
"problem": 2,
"blocked": 0,
"skipped": 0,
"left": 1
},
"teams": 4,
"locations": 2,
"fields": 1,
"leave": {
"new": 9,
"unchanged": 0,
"problem": 0,
"skipped": 0,
"days": 63.5
},
"balances": {
"new": 15,
"unchanged": 0,
"problem": 0,
"skipped": 0
},
"documents": {
"new": 0,
"unchanged": 0,
"problem": 0,
"skipped": 0,
"bytes": 0
},
"pay": 0,
"history": 0,
"jobs": {
"new": 0,
"problem": 0,
"skipped": 0
}
},
"problems": 2,
"report": {
"unmapped": [
"Cost center"
],
"warnings": [
"1 column is not imported: Cost center."
],
"teams": [
"Engineering",
"People"
],
"locations": [
"Berlin"
],
"fields": [
"Shirt size"
],
"blocking": [],
"storage": null
},
"progress": {
"done": 0,
"total": 0
},
"result": {
"added": 0,
"updated": 0,
"teams": 0,
"locations": 0,
"fields": 0,
"history": 0,
"pay": 0,
"pay_waiting": 0,
"leave": 0,
"balances": 0,
"documents": 0,
"problems": 0,
"payroll_notices": 0,
"numbers": 0
},
"undo": {
"available": false,
"until": null,
"undone_at": null,
"removed": 0,
"kept": []
},
"connection": null,
"started_by": {
"name": "Ana Ferreira"
},
"background": true,
"cancel_requested": false,
"error": null,
"created_at": "2026-10-12T09:00:00.000Z",
"updated_at": "2026-10-12T09:04:00.000Z",
"finished_at": null,
"expires_at": "2026-11-11T09:00:00.000Z"
}
}List moves#
POST/v1/migration/listRead
The company's moves from other HR tools of the last 30 days, newest first (at most 20), without sample values.
- Who can call it
- Manage key owner admin hr
- MCP tool
migration_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:
idstringrequiredtoolstring (enum)requiredOne of:
personio,factorial,sesame,hibob,bamboohr,meta4,other.statusstring (enum)requiredOne of:
reading,mapping,checking,checked,importing,undoing,done,cancelled,failed.phase"reading" | "checking" | "importing" | "undoing"requiredThe phase at work, or the one that stopped (cancelled, failed): migration_resume runs it again.
stepstring (enum)requiredImporting: the step at work (fields, people, history, pay, leave, balances, documents, finish).
One of:
fields,people,history,pay,leave,balances,documents,finish.sourceobjectrequired3 fields
kind"file" | "text" | "api"requiredfilesobject[]required3 fields
role"people" | "timeoff" | "history"requirednamestringrequiredsizeintegerrequired
connectorstring | nullrequired
sheetsobjectrequired3 fields
peopleobject | nullrequired4 fields
namestringrequiredrowsintegerrequiredcolumnsobject[]required4 fields
headerstringrequiredtargetstring | nullrequiredWhat the column feeds (null: not imported).
confidence"exact" | "likely" | "none"requiredexact: the tool's own name for it; likely: a usual name; none: not recognised.
samplesstring[]requiredThe first values (private columns as ••• for API keys and AI apps).
mapping_setbooleanrequired
timeoffobject | nullrequired4 fields
namestringrequiredrowsintegerrequiredcolumnsobject[]required4 fields
headerstringrequiredtargetstring | nullrequiredWhat the column feeds (null: not imported).
confidence"exact" | "likely" | "none"requiredexact: the tool's own name for it; likely: a usual name; none: not recognised.
samplesstring[]requiredThe first values (private columns as ••• for API keys and AI apps).
mapping_setbooleanrequired
historyobject | nullrequiredA job-history file: one row per person and date.
4 fields
namestringrequiredrowsintegerrequiredcolumnsobject[]required4 fields
headerstringrequiredtargetstring | nullrequiredWhat the column feeds (null: not imported).
confidence"exact" | "likely" | "none"requiredexact: the tool's own name for it; likely: a usual name; none: not recognised.
samplesstring[]requiredThe first values (private columns as ••• for API keys and AI apps).
mapping_setbooleanrequired
targetsobjectrequiredWhat a column can feed: the built-in targets, field:<key> for a custom field, new:<label> for a new text field.
3 fields
peoplestring[]requiredtimeoffstring[]requiredhistorystring[]required
scopeobjectrequired4 fields
paybooleanrequiredtimeoffbooleanrequireddocumentsbooleanrequiredhistorybooleanrequired
optionsobjectrequired8 fields
leave_typesobject[]required5 fields
sourcestringrequiredcountintegerrequiredtype_idstring | nullrequiredsuggestedbooleanrequireduses_balancebooleanrequired
entitiesobject[]requiredThe old tool's legal entities and the Bizisy legal entity each maps to.
4 fields
sourcestringrequiredcountintegerrequiredentitystring | nullrequiredThe Bizisy legal entity (legal name); null: the company's default one.
suggestedbooleanrequired
location_countrystring | nullrequiredeffective_datestring | nullrequiredpay_currencystringrequiredpay_period"year" | "month" | "hour"requiredvalue_mapsobject[]requiredCodes in the file (contract types, leaving reasons, sex…) and the Bizisy value each becomes (null: left out); suggested: Bizisy's guess, not chosen yet.
5 fields
targetstringrequiredsourcestringrequiredcountintegerrequiredvaluestring | nullrequiredsuggestedbooleanrequired
emailobjectrequiredHow people without a work email in the file get one: the company's pattern, or their personal email; null: the work email is required.
4 fields (one of several shapes)
Option 1
mode"pattern"requiredpattern"first.last" | "firstlast" | "f.last" | "first"requireddomainstringrequired
Option 2
mode"personal"required
countsobjectrequired10 fields
peopleobjectrequired7 fields
newintegerrequiredupdateintegerrequiredunchangedintegerrequiredproblemintegerrequiredblockedintegerrequiredskippedintegerrequiredleftintegerrequired
teamsintegerrequiredlocationsintegerrequiredfieldsintegerrequiredleaveobjectrequired5 fields
newintegerrequiredunchangedintegerrequiredproblemintegerrequiredskippedintegerrequireddaysnumberrequired
balancesobjectrequired4 fields
newintegerrequiredunchangedintegerrequiredproblemintegerrequiredskippedintegerrequired
documentsobjectrequired5 fields
newintegerrequiredunchangedintegerrequiredproblemintegerrequiredskippedintegerrequiredbytesnumberrequired
payintegerrequiredhistoryintegerrequiredjobsobjectrequiredRows of the job-history file: recorded with their person, to fix, left out.
3 fields
newintegerrequiredproblemintegerrequiredskippedintegerrequired
problemsintegerrequiredItems to fix or skip before importing (problems and blocked rows).
reportobjectrequired7 fields
unmappedstring[]requiredwarningsstring[]requiredteamsstring[]requiredlocationsstring[]requiredfieldsstring[]requiredblockingstring[]requiredstorageobject | nullrequired4 fields
bytesnumberrequiredincluded_bytesnumberrequiredused_bytesnumberrequiredprice_cents_per_gbnumberrequired
progressobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
resultobjectrequired14 fields
addedintegerrequiredupdatedintegerrequiredteamsintegerrequiredlocationsintegerrequiredfieldsintegerrequiredhistoryintegerrequiredpayintegerrequiredpay_waitingintegerPay sent for approval (Settings → Approval rules): it applies once another approver approves it.
Default
0.leaveintegerrequiredbalancesintegerrequireddocumentsintegerrequiredproblemsintegerrequiredpayroll_noticesintegerrequirednumbersintegerEmployee numbers set in Payroll.
Default
0.
undoobjectrequired5 fields
availablebooleanrequiredUndo can run now (within 24 hours of finishing, not undone yet).
untilstring | nullrequiredundone_atstring | nullrequiredremovedintegerrequiredkeptobject[]required3 fields
kindstringrequiredlabelstringrequiredreasonstringrequired
connectionobject | nullrequired2 fields
connectorstringrequiredremovedbooleanrequired
started_byobjectrequired1 field
namestringrequired
backgroundbooleanrequiredWhether the run works on the import job: follow it with migration_get.
cancel_requestedbooleanrequirederrorstring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredfinished_atstring | nullrequiredexpires_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/migration/list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/migration/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/migration/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": "mv1",
"tool": "personio",
"status": "checked",
"phase": null,
"step": null,
"source": {
"kind": "file",
"files": [
{
"role": "people",
"name": "personio-people.xlsx",
"size": 48211
},
{
"role": "timeoff",
"name": "absences.csv",
"size": 2104
}
],
"connector": null
},
"sheets": {
"people": {
"name": "personio-people.xlsx",
"rows": 16,
"mapping_set": true,
"columns": [
{
"header": "First name",
"target": "given_name",
"confidence": "exact",
"samples": []
},
{
"header": "Email",
"target": "work_email",
"confidence": "exact",
"samples": []
},
{
"header": "Cost center",
"target": null,
"confidence": "none",
"samples": []
}
]
},
"timeoff": null,
"history": null
},
"targets": {
"people": [
"given_name",
"family_name",
"work_email",
"title"
],
"timeoff": [
"person_email",
"leave_type",
"start",
"end"
],
"history": [
"person_id",
"from",
"title"
]
},
"scope": {
"pay": false,
"timeoff": true,
"documents": false,
"history": true
},
"options": {
"leave_types": [
{
"source": "Paid vacation",
"count": 7,
"type_id": "vacation",
"suggested": true,
"uses_balance": true
},
{
"source": "Sick leave",
"count": 2,
"type_id": null,
"suggested": false,
"uses_balance": false
}
],
"entities": [
{
"source": "Example Company GmbH",
"count": 7,
"entity": "Acme GmbH",
"suggested": true
}
],
"location_country": "PT",
"effective_date": null,
"pay_currency": "EUR",
"pay_period": "year",
"value_maps": [
{
"target": "contract_type",
"source": "CT02",
"count": 9,
"value": "fixed_term",
"suggested": false
}
],
"email": null
},
"counts": {
"people": {
"new": 12,
"update": 1,
"unchanged": 0,
"problem": 2,
"blocked": 0,
"skipped": 0,
"left": 1
},
"teams": 4,
"locations": 2,
"fields": 1,
"leave": {
"new": 9,
"unchanged": 0,
"problem": 0,
"skipped": 0,
"days": 63.5
},
"balances": {
"new": 15,
"unchanged": 0,
"problem": 0,
"skipped": 0
},
"documents": {
"new": 0,
"unchanged": 0,
"problem": 0,
"skipped": 0,
"bytes": 0
},
"pay": 0,
"history": 0,
"jobs": {
"new": 0,
"problem": 0,
"skipped": 0
}
},
"problems": 2,
"report": {
"unmapped": [
"Cost center"
],
"warnings": [
"1 column is not imported: Cost center."
],
"teams": [
"Engineering",
"People"
],
"locations": [
"Berlin"
],
"fields": [
"Shirt size"
],
"blocking": [],
"storage": null
},
"progress": {
"done": 0,
"total": 0
},
"result": {
"added": 0,
"updated": 0,
"teams": 0,
"locations": 0,
"fields": 0,
"history": 0,
"pay": 0,
"pay_waiting": 0,
"leave": 0,
"balances": 0,
"documents": 0,
"problems": 0,
"payroll_notices": 0,
"numbers": 0
},
"undo": {
"available": false,
"until": null,
"undone_at": null,
"removed": 0,
"kept": []
},
"connection": null,
"started_by": {
"name": "Ana Ferreira"
},
"background": true,
"cancel_requested": false,
"error": null,
"created_at": "2026-10-12T09:00:00.000Z",
"updated_at": "2026-10-12T09:04:00.000Z",
"finished_at": null,
"expires_at": "2026-11-11T09:00:00.000Z"
}
]
}List the rows of a move#
POST/v1/migration/itemsRead
The rows of a move in file order, at most 100 a page (after: the last n of the previous page): kind person, leave, balance or document; filter all, fix (problems and blocked), new, update, unchanged, skipped or applied. Each: outcome, changes (before → after; private and pay only as hidden), problems (the file's column, the message and the fix: edit, pick from options, or skip), the row's cells (null once applied; private and pay cells hidden from an API key or AI app).
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Private and pay cells are hidden.
- MCP tool
migration_itemson HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
run_idstringrequired1–64 characters.
kind"person" | "leave" | "balance" | "document" | "job"Default
"person".filterstring (enum)One of:
all,fix,new,update,unchanged,skipped,applied. Default"all".afterintegerAt least 0. Default
0.limitintegerFrom 1 to 100. Default
50.
Returns
itemsobject[]required15 fields
idstringrequiredkind"person" | "leave" | "balance" | "document" | "job"requirednintegerrequiredsheet"people" | "timeoff" | "history" | "api"requiredlabelstringrequiredemailstringrequiredoutcomestring (enum)requiredOne of:
pending,new,update,unchanged,problem,blocked,skipped.appliedbooleanrequiredskipbooleanrequiredbizisy_idstring | nullrequiredcreatedbooleanrequiredcellsstring[] | nullrequiredThe row as in the file, by header cell (null once applied; private and pay cells hidden from API keys and AI apps).
changesobject[]required4 fields
fieldstringrequiredbeforestring | nullrequiredafterstring | nullrequiredhiddenboolean
problemsobject[]required5 fields
columnstring | nullrequiredtargetstring | nullrequiredmessagestringrequiredfix"edit" | "pick" | "skip"requiredoptionsstring[]
notestring | nullrequired
nextinteger | nullrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/migration/items \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"run_id":"mv1","kind":"leave","filter":"fix","after":10,"limit":50}'const res = await fetch('https://api.bizisy.com/v1/migration/items', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"run_id": "mv1",
"kind": "leave",
"filter": "fix",
"after": 10,
"limit": 50
}),
});
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/migration/items",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"run_id": "mv1",
"kind": "leave",
"filter": "fix",
"after": 10,
"limit": 50,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"items": [
{
"id": "mv1:person:11",
"kind": "person",
"n": 11,
"sheet": "people",
"label": "Pierre Martin",
"email": "pierre.martin@example-company",
"outcome": "problem",
"applied": false,
"skip": false,
"bizisy_id": null,
"created": false,
"cells": [
"Pierre",
"pierre.martin@example-company",
"CC-SAL"
],
"changes": [],
"problems": [
{
"column": "Email",
"target": "work_email",
"message": "Use a valid email address.",
"fix": "edit"
}
],
"note": null
}
],
"next": null
}
}Fix or skip rows of a move#
POST/v1/migration/fix_itemsWrite
Changes rows not imported yet, at most 100 a call: set (values by column index, as in migration_items cells) or skip (true: leave the row out; false: take it back), then checks the move again (as migration_check). An API key or AI app fixes only moves it started, and never changes private or pay cells.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Only moves the key started; private and pay cells are kept as they were.
- MCP tool
migration_fix_itemson 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
run_idstringrequired1–64 characters.
itemsobject[]required1–100 items.
3 fields
idstringrequired1–200 characters.
setobject[]Up to 300 items.
2 fields
columnintegerrequiredFrom 0 to 299.
valuestringrequiredUp to 2000 characters.
skipboolean
Returns
25 fields
idstringrequiredtoolstring (enum)requiredOne of:
personio,factorial,sesame,hibob,bamboohr,meta4,other.statusstring (enum)requiredOne of:
reading,mapping,checking,checked,importing,undoing,done,cancelled,failed.phase"reading" | "checking" | "importing" | "undoing"requiredThe phase at work, or the one that stopped (cancelled, failed): migration_resume runs it again.
stepstring (enum)requiredImporting: the step at work (fields, people, history, pay, leave, balances, documents, finish).
One of:
fields,people,history,pay,leave,balances,documents,finish.sourceobjectrequired3 fields
kind"file" | "text" | "api"requiredfilesobject[]required3 fields
role"people" | "timeoff" | "history"requirednamestringrequiredsizeintegerrequired
connectorstring | nullrequired
sheetsobjectrequired3 fields
peopleobject | nullrequired4 fields
namestringrequiredrowsintegerrequiredcolumnsobject[]required4 fields
headerstringrequiredtargetstring | nullrequiredWhat the column feeds (null: not imported).
confidence"exact" | "likely" | "none"requiredexact: the tool's own name for it; likely: a usual name; none: not recognised.
samplesstring[]requiredThe first values (private columns as ••• for API keys and AI apps).
mapping_setbooleanrequired
timeoffobject | nullrequired4 fields
namestringrequiredrowsintegerrequiredcolumnsobject[]required4 fields
headerstringrequiredtargetstring | nullrequiredWhat the column feeds (null: not imported).
confidence"exact" | "likely" | "none"requiredexact: the tool's own name for it; likely: a usual name; none: not recognised.
samplesstring[]requiredThe first values (private columns as ••• for API keys and AI apps).
mapping_setbooleanrequired
historyobject | nullrequiredA job-history file: one row per person and date.
4 fields
namestringrequiredrowsintegerrequiredcolumnsobject[]required4 fields
headerstringrequiredtargetstring | nullrequiredWhat the column feeds (null: not imported).
confidence"exact" | "likely" | "none"requiredexact: the tool's own name for it; likely: a usual name; none: not recognised.
samplesstring[]requiredThe first values (private columns as ••• for API keys and AI apps).
mapping_setbooleanrequired
targetsobjectrequiredWhat a column can feed: the built-in targets, field:<key> for a custom field, new:<label> for a new text field.
3 fields
peoplestring[]requiredtimeoffstring[]requiredhistorystring[]required
scopeobjectrequired4 fields
paybooleanrequiredtimeoffbooleanrequireddocumentsbooleanrequiredhistorybooleanrequired
optionsobjectrequired8 fields
leave_typesobject[]required5 fields
sourcestringrequiredcountintegerrequiredtype_idstring | nullrequiredsuggestedbooleanrequireduses_balancebooleanrequired
entitiesobject[]requiredThe old tool's legal entities and the Bizisy legal entity each maps to.
4 fields
sourcestringrequiredcountintegerrequiredentitystring | nullrequiredThe Bizisy legal entity (legal name); null: the company's default one.
suggestedbooleanrequired
location_countrystring | nullrequiredeffective_datestring | nullrequiredpay_currencystringrequiredpay_period"year" | "month" | "hour"requiredvalue_mapsobject[]requiredCodes in the file (contract types, leaving reasons, sex…) and the Bizisy value each becomes (null: left out); suggested: Bizisy's guess, not chosen yet.
5 fields
targetstringrequiredsourcestringrequiredcountintegerrequiredvaluestring | nullrequiredsuggestedbooleanrequired
emailobjectrequiredHow people without a work email in the file get one: the company's pattern, or their personal email; null: the work email is required.
4 fields (one of several shapes)
Option 1
mode"pattern"requiredpattern"first.last" | "firstlast" | "f.last" | "first"requireddomainstringrequired
Option 2
mode"personal"required
countsobjectrequired10 fields
peopleobjectrequired7 fields
newintegerrequiredupdateintegerrequiredunchangedintegerrequiredproblemintegerrequiredblockedintegerrequiredskippedintegerrequiredleftintegerrequired
teamsintegerrequiredlocationsintegerrequiredfieldsintegerrequiredleaveobjectrequired5 fields
newintegerrequiredunchangedintegerrequiredproblemintegerrequiredskippedintegerrequireddaysnumberrequired
balancesobjectrequired4 fields
newintegerrequiredunchangedintegerrequiredproblemintegerrequiredskippedintegerrequired
documentsobjectrequired5 fields
newintegerrequiredunchangedintegerrequiredproblemintegerrequiredskippedintegerrequiredbytesnumberrequired
payintegerrequiredhistoryintegerrequiredjobsobjectrequiredRows of the job-history file: recorded with their person, to fix, left out.
3 fields
newintegerrequiredproblemintegerrequiredskippedintegerrequired
problemsintegerrequiredItems to fix or skip before importing (problems and blocked rows).
reportobjectrequired7 fields
unmappedstring[]requiredwarningsstring[]requiredteamsstring[]requiredlocationsstring[]requiredfieldsstring[]requiredblockingstring[]requiredstorageobject | nullrequired4 fields
bytesnumberrequiredincluded_bytesnumberrequiredused_bytesnumberrequiredprice_cents_per_gbnumberrequired
progressobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
resultobjectrequired14 fields
addedintegerrequiredupdatedintegerrequiredteamsintegerrequiredlocationsintegerrequiredfieldsintegerrequiredhistoryintegerrequiredpayintegerrequiredpay_waitingintegerPay sent for approval (Settings → Approval rules): it applies once another approver approves it.
Default
0.leaveintegerrequiredbalancesintegerrequireddocumentsintegerrequiredproblemsintegerrequiredpayroll_noticesintegerrequirednumbersintegerEmployee numbers set in Payroll.
Default
0.
undoobjectrequired5 fields
availablebooleanrequiredUndo can run now (within 24 hours of finishing, not undone yet).
untilstring | nullrequiredundone_atstring | nullrequiredremovedintegerrequiredkeptobject[]required3 fields
kindstringrequiredlabelstringrequiredreasonstringrequired
connectionobject | nullrequired2 fields
connectorstringrequiredremovedbooleanrequired
started_byobjectrequired1 field
namestringrequired
backgroundbooleanrequiredWhether the run works on the import job: follow it with migration_get.
cancel_requestedbooleanrequirederrorstring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredfinished_atstring | nullrequiredexpires_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/migration/fix_items \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"run_id": "mv1",
"items": [
{
"id": "mv1:person:11",
"set": [
{
"column": 1,
"value": "pierre.martin@example-company.eu"
}
]
},
{
"id": "mv1:person:12",
"skip": true
}
]
}'const res = await fetch('https://api.bizisy.com/v1/migration/fix_items', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"run_id": "mv1",
"items": [
{
"id": "mv1:person:11",
"set": [
{
"column": 1,
"value": "pierre.martin@example-company.eu"
}
]
},
{
"id": "mv1:person:12",
"skip": true
}
]
}),
});
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/migration/fix_items",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"run_id": "mv1",
"items": [
{
"id": "mv1:person:11",
"set": [
{
"column": 1,
"value": "pierre.martin@example-company.eu",
},
],
},
{
"id": "mv1:person:12",
"skip": True,
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "mv1",
"tool": "personio",
"status": "checked",
"phase": null,
"step": null,
"source": {
"kind": "file",
"files": [
{
"role": "people",
"name": "personio-people.xlsx",
"size": 48211
},
{
"role": "timeoff",
"name": "absences.csv",
"size": 2104
}
],
"connector": null
},
"sheets": {
"people": {
"name": "personio-people.xlsx",
"rows": 16,
"mapping_set": true,
"columns": [
{
"header": "First name",
"target": "given_name",
"confidence": "exact",
"samples": [
"Sofia",
"Lukas"
]
},
{
"header": "Email",
"target": "work_email",
"confidence": "exact",
"samples": [
"sofia.almeida@example-company.eu",
"lukas.becker@example-company.eu"
]
},
{
"header": "Cost center",
"target": null,
"confidence": "none",
"samples": [
"CC-MAN",
"CC-ENG"
]
}
]
},
"timeoff": {
"name": "absences.csv",
"rows": 9,
"mapping_set": true,
"columns": [
{
"header": "Absence type",
"target": "leave_type",
"confidence": "exact",
"samples": [
"Paid vacation"
]
}
]
},
"history": null
},
"targets": {
"people": [
"given_name",
"family_name",
"work_email",
"title"
],
"timeoff": [
"person_email",
"leave_type",
"start",
"end"
],
"history": [
"person_id",
"from",
"title"
]
},
"scope": {
"pay": false,
"timeoff": true,
"documents": false,
"history": true
},
"options": {
"leave_types": [
{
"source": "Paid vacation",
"count": 7,
"type_id": "vacation",
"suggested": true,
"uses_balance": true
},
{
"source": "Sick leave",
"count": 2,
"type_id": null,
"suggested": false,
"uses_balance": false
}
],
"entities": [
{
"source": "Example Company GmbH",
"count": 7,
"entity": "Acme GmbH",
"suggested": true
}
],
"location_country": "PT",
"effective_date": null,
"pay_currency": "EUR",
"pay_period": "year",
"value_maps": [
{
"target": "contract_type",
"source": "CT02",
"count": 9,
"value": "fixed_term",
"suggested": false
}
],
"email": null
},
"counts": {
"people": {
"new": 12,
"update": 1,
"unchanged": 0,
"problem": 2,
"blocked": 0,
"skipped": 0,
"left": 1
},
"teams": 4,
"locations": 2,
"fields": 1,
"leave": {
"new": 9,
"unchanged": 0,
"problem": 0,
"skipped": 0,
"days": 63.5
},
"balances": {
"new": 15,
"unchanged": 0,
"problem": 0,
"skipped": 0
},
"documents": {
"new": 0,
"unchanged": 0,
"problem": 0,
"skipped": 0,
"bytes": 0
},
"pay": 0,
"history": 0,
"jobs": {
"new": 0,
"problem": 0,
"skipped": 0
}
},
"problems": 2,
"report": {
"unmapped": [
"Cost center"
],
"warnings": [
"1 column is not imported: Cost center."
],
"teams": [
"Engineering",
"People"
],
"locations": [
"Berlin"
],
"fields": [
"Shirt size"
],
"blocking": [],
"storage": null
},
"progress": {
"done": 0,
"total": 0
},
"result": {
"added": 0,
"updated": 0,
"teams": 0,
"locations": 0,
"fields": 0,
"history": 0,
"pay": 0,
"pay_waiting": 0,
"leave": 0,
"balances": 0,
"documents": 0,
"problems": 0,
"payroll_notices": 0,
"numbers": 0
},
"undo": {
"available": false,
"until": null,
"undone_at": null,
"removed": 0,
"kept": []
},
"connection": null,
"started_by": {
"name": "Ana Ferreira"
},
"background": true,
"cancel_requested": false,
"error": null,
"created_at": "2026-10-12T09:00:00.000Z",
"updated_at": "2026-10-12T09:04:00.000Z",
"finished_at": null,
"expires_at": "2026-11-11T09:00:00.000Z"
}
}Import a checked move#
POST/v1/migration/importWrite
Imports a checked move: new custom fields, then people with their teams and locations (managers first), their job history and pay (when in scope), leave and balances, and documents, in that order. Rows with problems, blocked or skipped are left out (fix them and import again later; nothing is imported twice). Nobody is emailed and no onboarding checklist starts; the security notice of a changed bank account for people already in Bizisy is sent as always. In Bizisy it runs in the background (status importing, step, progress: follow with migration_get; cancel with migration_cancel); an API key or AI app imports at most 250 people at once, people only. Undo is possible for 24 hours (migration_undo). Always show the check (migration_get counts and report, migration_items) and ask before importing.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- At most 250 people, people only, inside the call; only moves the key started.
- MCP tool
migration_importon 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
run_idstringrequired1–64 characters.
Returns
25 fields
idstringrequiredtoolstring (enum)requiredOne of:
personio,factorial,sesame,hibob,bamboohr,meta4,other.statusstring (enum)requiredOne of:
reading,mapping,checking,checked,importing,undoing,done,cancelled,failed.phase"reading" | "checking" | "importing" | "undoing"requiredThe phase at work, or the one that stopped (cancelled, failed): migration_resume runs it again.
stepstring (enum)requiredImporting: the step at work (fields, people, history, pay, leave, balances, documents, finish).
One of:
fields,people,history,pay,leave,balances,documents,finish.sourceobjectrequired3 fields
kind"file" | "text" | "api"requiredfilesobject[]required3 fields
role"people" | "timeoff" | "history"requirednamestringrequiredsizeintegerrequired
connectorstring | nullrequired
sheetsobjectrequired3 fields
peopleobject | nullrequired4 fields
namestringrequiredrowsintegerrequiredcolumnsobject[]required4 fields
headerstringrequiredtargetstring | nullrequiredWhat the column feeds (null: not imported).
confidence"exact" | "likely" | "none"requiredexact: the tool's own name for it; likely: a usual name; none: not recognised.
samplesstring[]requiredThe first values (private columns as ••• for API keys and AI apps).
mapping_setbooleanrequired
timeoffobject | nullrequired4 fields
namestringrequiredrowsintegerrequiredcolumnsobject[]required4 fields
headerstringrequiredtargetstring | nullrequiredWhat the column feeds (null: not imported).
confidence"exact" | "likely" | "none"requiredexact: the tool's own name for it; likely: a usual name; none: not recognised.
samplesstring[]requiredThe first values (private columns as ••• for API keys and AI apps).
mapping_setbooleanrequired
historyobject | nullrequiredA job-history file: one row per person and date.
4 fields
namestringrequiredrowsintegerrequiredcolumnsobject[]required4 fields
headerstringrequiredtargetstring | nullrequiredWhat the column feeds (null: not imported).
confidence"exact" | "likely" | "none"requiredexact: the tool's own name for it; likely: a usual name; none: not recognised.
samplesstring[]requiredThe first values (private columns as ••• for API keys and AI apps).
mapping_setbooleanrequired
targetsobjectrequiredWhat a column can feed: the built-in targets, field:<key> for a custom field, new:<label> for a new text field.
3 fields
peoplestring[]requiredtimeoffstring[]requiredhistorystring[]required
scopeobjectrequired4 fields
paybooleanrequiredtimeoffbooleanrequireddocumentsbooleanrequiredhistorybooleanrequired
optionsobjectrequired8 fields
leave_typesobject[]required5 fields
sourcestringrequiredcountintegerrequiredtype_idstring | nullrequiredsuggestedbooleanrequireduses_balancebooleanrequired
entitiesobject[]requiredThe old tool's legal entities and the Bizisy legal entity each maps to.
4 fields
sourcestringrequiredcountintegerrequiredentitystring | nullrequiredThe Bizisy legal entity (legal name); null: the company's default one.
suggestedbooleanrequired
location_countrystring | nullrequiredeffective_datestring | nullrequiredpay_currencystringrequiredpay_period"year" | "month" | "hour"requiredvalue_mapsobject[]requiredCodes in the file (contract types, leaving reasons, sex…) and the Bizisy value each becomes (null: left out); suggested: Bizisy's guess, not chosen yet.
5 fields
targetstringrequiredsourcestringrequiredcountintegerrequiredvaluestring | nullrequiredsuggestedbooleanrequired
emailobjectrequiredHow people without a work email in the file get one: the company's pattern, or their personal email; null: the work email is required.
4 fields (one of several shapes)
Option 1
mode"pattern"requiredpattern"first.last" | "firstlast" | "f.last" | "first"requireddomainstringrequired
Option 2
mode"personal"required
countsobjectrequired10 fields
peopleobjectrequired7 fields
newintegerrequiredupdateintegerrequiredunchangedintegerrequiredproblemintegerrequiredblockedintegerrequiredskippedintegerrequiredleftintegerrequired
teamsintegerrequiredlocationsintegerrequiredfieldsintegerrequiredleaveobjectrequired5 fields
newintegerrequiredunchangedintegerrequiredproblemintegerrequiredskippedintegerrequireddaysnumberrequired
balancesobjectrequired4 fields
newintegerrequiredunchangedintegerrequiredproblemintegerrequiredskippedintegerrequired
documentsobjectrequired5 fields
newintegerrequiredunchangedintegerrequiredproblemintegerrequiredskippedintegerrequiredbytesnumberrequired
payintegerrequiredhistoryintegerrequiredjobsobjectrequiredRows of the job-history file: recorded with their person, to fix, left out.
3 fields
newintegerrequiredproblemintegerrequiredskippedintegerrequired
problemsintegerrequiredItems to fix or skip before importing (problems and blocked rows).
reportobjectrequired7 fields
unmappedstring[]requiredwarningsstring[]requiredteamsstring[]requiredlocationsstring[]requiredfieldsstring[]requiredblockingstring[]requiredstorageobject | nullrequired4 fields
bytesnumberrequiredincluded_bytesnumberrequiredused_bytesnumberrequiredprice_cents_per_gbnumberrequired
progressobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
resultobjectrequired14 fields
addedintegerrequiredupdatedintegerrequiredteamsintegerrequiredlocationsintegerrequiredfieldsintegerrequiredhistoryintegerrequiredpayintegerrequiredpay_waitingintegerPay sent for approval (Settings → Approval rules): it applies once another approver approves it.
Default
0.leaveintegerrequiredbalancesintegerrequireddocumentsintegerrequiredproblemsintegerrequiredpayroll_noticesintegerrequirednumbersintegerEmployee numbers set in Payroll.
Default
0.
undoobjectrequired5 fields
availablebooleanrequiredUndo can run now (within 24 hours of finishing, not undone yet).
untilstring | nullrequiredundone_atstring | nullrequiredremovedintegerrequiredkeptobject[]required3 fields
kindstringrequiredlabelstringrequiredreasonstringrequired
connectionobject | nullrequired2 fields
connectorstringrequiredremovedbooleanrequired
started_byobjectrequired1 field
namestringrequired
backgroundbooleanrequiredWhether the run works on the import job: follow it with migration_get.
cancel_requestedbooleanrequirederrorstring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredfinished_atstring | nullrequiredexpires_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/migration/import \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"run_id":"mv1"}'const res = await fetch('https://api.bizisy.com/v1/migration/import', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"run_id": "mv1"
}),
});
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/migration/import",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"run_id": "mv1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "mv1",
"tool": "personio",
"status": "importing",
"phase": "importing",
"step": "people",
"source": {
"kind": "file",
"files": [
{
"role": "people",
"name": "personio-people.xlsx",
"size": 48211
},
{
"role": "timeoff",
"name": "absences.csv",
"size": 2104
}
],
"connector": null
},
"sheets": {
"people": {
"name": "personio-people.xlsx",
"rows": 16,
"mapping_set": true,
"columns": [
{
"header": "First name",
"target": "given_name",
"confidence": "exact",
"samples": [
"Sofia",
"Lukas"
]
},
{
"header": "Email",
"target": "work_email",
"confidence": "exact",
"samples": [
"sofia.almeida@example-company.eu",
"lukas.becker@example-company.eu"
]
},
{
"header": "Cost center",
"target": null,
"confidence": "none",
"samples": [
"CC-MAN",
"CC-ENG"
]
}
]
},
"timeoff": {
"name": "absences.csv",
"rows": 9,
"mapping_set": true,
"columns": [
{
"header": "Absence type",
"target": "leave_type",
"confidence": "exact",
"samples": [
"Paid vacation"
]
}
]
},
"history": null
},
"targets": {
"people": [
"given_name",
"family_name",
"work_email",
"title"
],
"timeoff": [
"person_email",
"leave_type",
"start",
"end"
],
"history": [
"person_id",
"from",
"title"
]
},
"scope": {
"pay": false,
"timeoff": true,
"documents": false,
"history": true
},
"options": {
"leave_types": [
{
"source": "Paid vacation",
"count": 7,
"type_id": "vacation",
"suggested": true,
"uses_balance": true
},
{
"source": "Sick leave",
"count": 2,
"type_id": null,
"suggested": false,
"uses_balance": false
}
],
"entities": [
{
"source": "Example Company GmbH",
"count": 7,
"entity": "Acme GmbH",
"suggested": true
}
],
"location_country": "PT",
"effective_date": null,
"pay_currency": "EUR",
"pay_period": "year",
"value_maps": [
{
"target": "contract_type",
"source": "CT02",
"count": 9,
"value": "fixed_term",
"suggested": false
}
],
"email": null
},
"counts": {
"people": {
"new": 12,
"update": 1,
"unchanged": 0,
"problem": 2,
"blocked": 0,
"skipped": 0,
"left": 1
},
"teams": 4,
"locations": 2,
"fields": 1,
"leave": {
"new": 9,
"unchanged": 0,
"problem": 0,
"skipped": 0,
"days": 63.5
},
"balances": {
"new": 15,
"unchanged": 0,
"problem": 0,
"skipped": 0
},
"documents": {
"new": 0,
"unchanged": 0,
"problem": 0,
"skipped": 0,
"bytes": 0
},
"pay": 0,
"history": 0,
"jobs": {
"new": 0,
"problem": 0,
"skipped": 0
}
},
"problems": 2,
"report": {
"unmapped": [
"Cost center"
],
"warnings": [
"1 column is not imported: Cost center."
],
"teams": [
"Engineering",
"People"
],
"locations": [
"Berlin"
],
"fields": [
"Shirt size"
],
"blocking": [],
"storage": null
},
"progress": {
"done": 50,
"total": 142
},
"result": {
"added": 0,
"updated": 0,
"teams": 0,
"locations": 0,
"fields": 0,
"history": 0,
"pay": 0,
"pay_waiting": 0,
"leave": 0,
"balances": 0,
"documents": 0,
"problems": 0,
"payroll_notices": 0,
"numbers": 0
},
"undo": {
"available": false,
"until": null,
"undone_at": null,
"removed": 0,
"kept": []
},
"connection": null,
"started_by": {
"name": "Ana Ferreira"
},
"background": true,
"cancel_requested": false,
"error": null,
"created_at": "2026-10-12T09:00:00.000Z",
"updated_at": "2026-10-12T09:04:00.000Z",
"finished_at": null,
"expires_at": "2026-11-11T09:00:00.000Z"
}
}Cancel a move#
POST/v1/migration/cancelWrite
Stops a move that is working: while reading or checking nothing was written; while importing it stops after the current batch (what was imported stays). Resume it later (migration_resume) or discard it.
- Who can call it
- Manage key owner admin hr
- MCP tool
migration_cancelon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
run_idstringrequired1–64 characters.
Returns
25 fields
idstringrequiredtoolstring (enum)requiredOne of:
personio,factorial,sesame,hibob,bamboohr,meta4,other.statusstring (enum)requiredOne of:
reading,mapping,checking,checked,importing,undoing,done,cancelled,failed.phase"reading" | "checking" | "importing" | "undoing"requiredThe phase at work, or the one that stopped (cancelled, failed): migration_resume runs it again.
stepstring (enum)requiredImporting: the step at work (fields, people, history, pay, leave, balances, documents, finish).
One of:
fields,people,history,pay,leave,balances,documents,finish.sourceobjectrequired3 fields
kind"file" | "text" | "api"requiredfilesobject[]required3 fields
role"people" | "timeoff" | "history"requirednamestringrequiredsizeintegerrequired
connectorstring | nullrequired
sheetsobjectrequired3 fields
peopleobject | nullrequired4 fields
namestringrequiredrowsintegerrequiredcolumnsobject[]required4 fields
headerstringrequiredtargetstring | nullrequiredWhat the column feeds (null: not imported).
confidence"exact" | "likely" | "none"requiredexact: the tool's own name for it; likely: a usual name; none: not recognised.
samplesstring[]requiredThe first values (private columns as ••• for API keys and AI apps).
mapping_setbooleanrequired
timeoffobject | nullrequired4 fields
namestringrequiredrowsintegerrequiredcolumnsobject[]required4 fields
headerstringrequiredtargetstring | nullrequiredWhat the column feeds (null: not imported).
confidence"exact" | "likely" | "none"requiredexact: the tool's own name for it; likely: a usual name; none: not recognised.
samplesstring[]requiredThe first values (private columns as ••• for API keys and AI apps).
mapping_setbooleanrequired
historyobject | nullrequiredA job-history file: one row per person and date.
4 fields
namestringrequiredrowsintegerrequiredcolumnsobject[]required4 fields
headerstringrequiredtargetstring | nullrequiredWhat the column feeds (null: not imported).
confidence"exact" | "likely" | "none"requiredexact: the tool's own name for it; likely: a usual name; none: not recognised.
samplesstring[]requiredThe first values (private columns as ••• for API keys and AI apps).
mapping_setbooleanrequired
targetsobjectrequiredWhat a column can feed: the built-in targets, field:<key> for a custom field, new:<label> for a new text field.
3 fields
peoplestring[]requiredtimeoffstring[]requiredhistorystring[]required
scopeobjectrequired4 fields
paybooleanrequiredtimeoffbooleanrequireddocumentsbooleanrequiredhistorybooleanrequired
optionsobjectrequired8 fields
leave_typesobject[]required5 fields
sourcestringrequiredcountintegerrequiredtype_idstring | nullrequiredsuggestedbooleanrequireduses_balancebooleanrequired
entitiesobject[]requiredThe old tool's legal entities and the Bizisy legal entity each maps to.
4 fields
sourcestringrequiredcountintegerrequiredentitystring | nullrequiredThe Bizisy legal entity (legal name); null: the company's default one.
suggestedbooleanrequired
location_countrystring | nullrequiredeffective_datestring | nullrequiredpay_currencystringrequiredpay_period"year" | "month" | "hour"requiredvalue_mapsobject[]requiredCodes in the file (contract types, leaving reasons, sex…) and the Bizisy value each becomes (null: left out); suggested: Bizisy's guess, not chosen yet.
5 fields
targetstringrequiredsourcestringrequiredcountintegerrequiredvaluestring | nullrequiredsuggestedbooleanrequired
emailobjectrequiredHow people without a work email in the file get one: the company's pattern, or their personal email; null: the work email is required.
4 fields (one of several shapes)
Option 1
mode"pattern"requiredpattern"first.last" | "firstlast" | "f.last" | "first"requireddomainstringrequired
Option 2
mode"personal"required
countsobjectrequired10 fields
peopleobjectrequired7 fields
newintegerrequiredupdateintegerrequiredunchangedintegerrequiredproblemintegerrequiredblockedintegerrequiredskippedintegerrequiredleftintegerrequired
teamsintegerrequiredlocationsintegerrequiredfieldsintegerrequiredleaveobjectrequired5 fields
newintegerrequiredunchangedintegerrequiredproblemintegerrequiredskippedintegerrequireddaysnumberrequired
balancesobjectrequired4 fields
newintegerrequiredunchangedintegerrequiredproblemintegerrequiredskippedintegerrequired
documentsobjectrequired5 fields
newintegerrequiredunchangedintegerrequiredproblemintegerrequiredskippedintegerrequiredbytesnumberrequired
payintegerrequiredhistoryintegerrequiredjobsobjectrequiredRows of the job-history file: recorded with their person, to fix, left out.
3 fields
newintegerrequiredproblemintegerrequiredskippedintegerrequired
problemsintegerrequiredItems to fix or skip before importing (problems and blocked rows).
reportobjectrequired7 fields
unmappedstring[]requiredwarningsstring[]requiredteamsstring[]requiredlocationsstring[]requiredfieldsstring[]requiredblockingstring[]requiredstorageobject | nullrequired4 fields
bytesnumberrequiredincluded_bytesnumberrequiredused_bytesnumberrequiredprice_cents_per_gbnumberrequired
progressobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
resultobjectrequired14 fields
addedintegerrequiredupdatedintegerrequiredteamsintegerrequiredlocationsintegerrequiredfieldsintegerrequiredhistoryintegerrequiredpayintegerrequiredpay_waitingintegerPay sent for approval (Settings → Approval rules): it applies once another approver approves it.
Default
0.leaveintegerrequiredbalancesintegerrequireddocumentsintegerrequiredproblemsintegerrequiredpayroll_noticesintegerrequirednumbersintegerEmployee numbers set in Payroll.
Default
0.
undoobjectrequired5 fields
availablebooleanrequiredUndo can run now (within 24 hours of finishing, not undone yet).
untilstring | nullrequiredundone_atstring | nullrequiredremovedintegerrequiredkeptobject[]required3 fields
kindstringrequiredlabelstringrequiredreasonstringrequired
connectionobject | nullrequired2 fields
connectorstringrequiredremovedbooleanrequired
started_byobjectrequired1 field
namestringrequired
backgroundbooleanrequiredWhether the run works on the import job: follow it with migration_get.
cancel_requestedbooleanrequirederrorstring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredfinished_atstring | nullrequiredexpires_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/migration/cancel \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"run_id":"mv1"}'const res = await fetch('https://api.bizisy.com/v1/migration/cancel', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"run_id": "mv1"
}),
});
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/migration/cancel",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"run_id": "mv1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "mv1",
"tool": "personio",
"status": "importing",
"phase": "importing",
"step": "people",
"source": {
"kind": "file",
"files": [
{
"role": "people",
"name": "personio-people.xlsx",
"size": 48211
},
{
"role": "timeoff",
"name": "absences.csv",
"size": 2104
}
],
"connector": null
},
"sheets": {
"people": {
"name": "personio-people.xlsx",
"rows": 16,
"mapping_set": true,
"columns": [
{
"header": "First name",
"target": "given_name",
"confidence": "exact",
"samples": [
"Sofia",
"Lukas"
]
},
{
"header": "Email",
"target": "work_email",
"confidence": "exact",
"samples": [
"sofia.almeida@example-company.eu",
"lukas.becker@example-company.eu"
]
},
{
"header": "Cost center",
"target": null,
"confidence": "none",
"samples": [
"CC-MAN",
"CC-ENG"
]
}
]
},
"timeoff": {
"name": "absences.csv",
"rows": 9,
"mapping_set": true,
"columns": [
{
"header": "Absence type",
"target": "leave_type",
"confidence": "exact",
"samples": [
"Paid vacation"
]
}
]
},
"history": null
},
"targets": {
"people": [
"given_name",
"family_name",
"work_email",
"title"
],
"timeoff": [
"person_email",
"leave_type",
"start",
"end"
],
"history": [
"person_id",
"from",
"title"
]
},
"scope": {
"pay": false,
"timeoff": true,
"documents": false,
"history": true
},
"options": {
"leave_types": [
{
"source": "Paid vacation",
"count": 7,
"type_id": "vacation",
"suggested": true,
"uses_balance": true
},
{
"source": "Sick leave",
"count": 2,
"type_id": null,
"suggested": false,
"uses_balance": false
}
],
"entities": [
{
"source": "Example Company GmbH",
"count": 7,
"entity": "Acme GmbH",
"suggested": true
}
],
"location_country": "PT",
"effective_date": null,
"pay_currency": "EUR",
"pay_period": "year",
"value_maps": [
{
"target": "contract_type",
"source": "CT02",
"count": 9,
"value": "fixed_term",
"suggested": false
}
],
"email": null
},
"counts": {
"people": {
"new": 12,
"update": 1,
"unchanged": 0,
"problem": 2,
"blocked": 0,
"skipped": 0,
"left": 1
},
"teams": 4,
"locations": 2,
"fields": 1,
"leave": {
"new": 9,
"unchanged": 0,
"problem": 0,
"skipped": 0,
"days": 63.5
},
"balances": {
"new": 15,
"unchanged": 0,
"problem": 0,
"skipped": 0
},
"documents": {
"new": 0,
"unchanged": 0,
"problem": 0,
"skipped": 0,
"bytes": 0
},
"pay": 0,
"history": 0,
"jobs": {
"new": 0,
"problem": 0,
"skipped": 0
}
},
"problems": 2,
"report": {
"unmapped": [
"Cost center"
],
"warnings": [
"1 column is not imported: Cost center."
],
"teams": [
"Engineering",
"People"
],
"locations": [
"Berlin"
],
"fields": [
"Shirt size"
],
"blocking": [],
"storage": null
},
"progress": {
"done": 0,
"total": 0
},
"result": {
"added": 0,
"updated": 0,
"teams": 0,
"locations": 0,
"fields": 0,
"history": 0,
"pay": 0,
"pay_waiting": 0,
"leave": 0,
"balances": 0,
"documents": 0,
"problems": 0,
"payroll_notices": 0,
"numbers": 0
},
"undo": {
"available": false,
"until": null,
"undone_at": null,
"removed": 0,
"kept": []
},
"connection": null,
"started_by": {
"name": "Ana Ferreira"
},
"background": true,
"cancel_requested": true,
"error": null,
"created_at": "2026-10-12T09:00:00.000Z",
"updated_at": "2026-10-12T09:04:00.000Z",
"finished_at": null,
"expires_at": "2026-11-11T09:00:00.000Z"
}
}Resume a move#
POST/v1/migration/resumeWrite
Runs the phase of a cancelled or failed move again (reading, checking, importing or undoing); rows already imported are never written twice. Only by someone signed in to Bizisy, never through an API key or AI app.
- Web app only
- Refused for API keys and connected apps. A move in the background is resumed by a person signed in to Bizisy.
- MCP tool
migration_resumeon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
run_idstringrequired1–64 characters.
Returns
25 fields
idstringrequiredtoolstring (enum)requiredOne of:
personio,factorial,sesame,hibob,bamboohr,meta4,other.statusstring (enum)requiredOne of:
reading,mapping,checking,checked,importing,undoing,done,cancelled,failed.phase"reading" | "checking" | "importing" | "undoing"requiredThe phase at work, or the one that stopped (cancelled, failed): migration_resume runs it again.
stepstring (enum)requiredImporting: the step at work (fields, people, history, pay, leave, balances, documents, finish).
One of:
fields,people,history,pay,leave,balances,documents,finish.sourceobjectrequired3 fields
kind"file" | "text" | "api"requiredfilesobject[]required3 fields
role"people" | "timeoff" | "history"requirednamestringrequiredsizeintegerrequired
connectorstring | nullrequired
sheetsobjectrequired3 fields
peopleobject | nullrequired4 fields
namestringrequiredrowsintegerrequiredcolumnsobject[]required4 fields
headerstringrequiredtargetstring | nullrequiredWhat the column feeds (null: not imported).
confidence"exact" | "likely" | "none"requiredexact: the tool's own name for it; likely: a usual name; none: not recognised.
samplesstring[]requiredThe first values (private columns as ••• for API keys and AI apps).
mapping_setbooleanrequired
timeoffobject | nullrequired4 fields
namestringrequiredrowsintegerrequiredcolumnsobject[]required4 fields
headerstringrequiredtargetstring | nullrequiredWhat the column feeds (null: not imported).
confidence"exact" | "likely" | "none"requiredexact: the tool's own name for it; likely: a usual name; none: not recognised.
samplesstring[]requiredThe first values (private columns as ••• for API keys and AI apps).
mapping_setbooleanrequired
historyobject | nullrequiredA job-history file: one row per person and date.
4 fields
namestringrequiredrowsintegerrequiredcolumnsobject[]required4 fields
headerstringrequiredtargetstring | nullrequiredWhat the column feeds (null: not imported).
confidence"exact" | "likely" | "none"requiredexact: the tool's own name for it; likely: a usual name; none: not recognised.
samplesstring[]requiredThe first values (private columns as ••• for API keys and AI apps).
mapping_setbooleanrequired
targetsobjectrequiredWhat a column can feed: the built-in targets, field:<key> for a custom field, new:<label> for a new text field.
3 fields
peoplestring[]requiredtimeoffstring[]requiredhistorystring[]required
scopeobjectrequired4 fields
paybooleanrequiredtimeoffbooleanrequireddocumentsbooleanrequiredhistorybooleanrequired
optionsobjectrequired8 fields
leave_typesobject[]required5 fields
sourcestringrequiredcountintegerrequiredtype_idstring | nullrequiredsuggestedbooleanrequireduses_balancebooleanrequired
entitiesobject[]requiredThe old tool's legal entities and the Bizisy legal entity each maps to.
4 fields
sourcestringrequiredcountintegerrequiredentitystring | nullrequiredThe Bizisy legal entity (legal name); null: the company's default one.
suggestedbooleanrequired
location_countrystring | nullrequiredeffective_datestring | nullrequiredpay_currencystringrequiredpay_period"year" | "month" | "hour"requiredvalue_mapsobject[]requiredCodes in the file (contract types, leaving reasons, sex…) and the Bizisy value each becomes (null: left out); suggested: Bizisy's guess, not chosen yet.
5 fields
targetstringrequiredsourcestringrequiredcountintegerrequiredvaluestring | nullrequiredsuggestedbooleanrequired
emailobjectrequiredHow people without a work email in the file get one: the company's pattern, or their personal email; null: the work email is required.
4 fields (one of several shapes)
Option 1
mode"pattern"requiredpattern"first.last" | "firstlast" | "f.last" | "first"requireddomainstringrequired
Option 2
mode"personal"required
countsobjectrequired10 fields
peopleobjectrequired7 fields
newintegerrequiredupdateintegerrequiredunchangedintegerrequiredproblemintegerrequiredblockedintegerrequiredskippedintegerrequiredleftintegerrequired
teamsintegerrequiredlocationsintegerrequiredfieldsintegerrequiredleaveobjectrequired5 fields
newintegerrequiredunchangedintegerrequiredproblemintegerrequiredskippedintegerrequireddaysnumberrequired
balancesobjectrequired4 fields
newintegerrequiredunchangedintegerrequiredproblemintegerrequiredskippedintegerrequired
documentsobjectrequired5 fields
newintegerrequiredunchangedintegerrequiredproblemintegerrequiredskippedintegerrequiredbytesnumberrequired
payintegerrequiredhistoryintegerrequiredjobsobjectrequiredRows of the job-history file: recorded with their person, to fix, left out.
3 fields
newintegerrequiredproblemintegerrequiredskippedintegerrequired
problemsintegerrequiredItems to fix or skip before importing (problems and blocked rows).
reportobjectrequired7 fields
unmappedstring[]requiredwarningsstring[]requiredteamsstring[]requiredlocationsstring[]requiredfieldsstring[]requiredblockingstring[]requiredstorageobject | nullrequired4 fields
bytesnumberrequiredincluded_bytesnumberrequiredused_bytesnumberrequiredprice_cents_per_gbnumberrequired
progressobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
resultobjectrequired14 fields
addedintegerrequiredupdatedintegerrequiredteamsintegerrequiredlocationsintegerrequiredfieldsintegerrequiredhistoryintegerrequiredpayintegerrequiredpay_waitingintegerPay sent for approval (Settings → Approval rules): it applies once another approver approves it.
Default
0.leaveintegerrequiredbalancesintegerrequireddocumentsintegerrequiredproblemsintegerrequiredpayroll_noticesintegerrequirednumbersintegerEmployee numbers set in Payroll.
Default
0.
undoobjectrequired5 fields
availablebooleanrequiredUndo can run now (within 24 hours of finishing, not undone yet).
untilstring | nullrequiredundone_atstring | nullrequiredremovedintegerrequiredkeptobject[]required3 fields
kindstringrequiredlabelstringrequiredreasonstringrequired
connectionobject | nullrequired2 fields
connectorstringrequiredremovedbooleanrequired
started_byobjectrequired1 field
namestringrequired
backgroundbooleanrequiredWhether the run works on the import job: follow it with migration_get.
cancel_requestedbooleanrequirederrorstring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredfinished_atstring | nullrequiredexpires_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/migration/resume \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"run_id":"mv1"}'const res = await fetch('https://api.bizisy.com/v1/migration/resume', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"run_id": "mv1"
}),
});
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/migration/resume",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"run_id": "mv1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "mv1",
"tool": "personio",
"status": "importing",
"phase": "importing",
"step": "leave",
"source": {
"kind": "file",
"files": [
{
"role": "people",
"name": "personio-people.xlsx",
"size": 48211
},
{
"role": "timeoff",
"name": "absences.csv",
"size": 2104
}
],
"connector": null
},
"sheets": {
"people": {
"name": "personio-people.xlsx",
"rows": 16,
"mapping_set": true,
"columns": [
{
"header": "First name",
"target": "given_name",
"confidence": "exact",
"samples": [
"Sofia",
"Lukas"
]
},
{
"header": "Email",
"target": "work_email",
"confidence": "exact",
"samples": [
"sofia.almeida@example-company.eu",
"lukas.becker@example-company.eu"
]
},
{
"header": "Cost center",
"target": null,
"confidence": "none",
"samples": [
"CC-MAN",
"CC-ENG"
]
}
]
},
"timeoff": {
"name": "absences.csv",
"rows": 9,
"mapping_set": true,
"columns": [
{
"header": "Absence type",
"target": "leave_type",
"confidence": "exact",
"samples": [
"Paid vacation"
]
}
]
},
"history": null
},
"targets": {
"people": [
"given_name",
"family_name",
"work_email",
"title"
],
"timeoff": [
"person_email",
"leave_type",
"start",
"end"
],
"history": [
"person_id",
"from",
"title"
]
},
"scope": {
"pay": false,
"timeoff": true,
"documents": false,
"history": true
},
"options": {
"leave_types": [
{
"source": "Paid vacation",
"count": 7,
"type_id": "vacation",
"suggested": true,
"uses_balance": true
},
{
"source": "Sick leave",
"count": 2,
"type_id": null,
"suggested": false,
"uses_balance": false
}
],
"entities": [
{
"source": "Example Company GmbH",
"count": 7,
"entity": "Acme GmbH",
"suggested": true
}
],
"location_country": "PT",
"effective_date": null,
"pay_currency": "EUR",
"pay_period": "year",
"value_maps": [
{
"target": "contract_type",
"source": "CT02",
"count": 9,
"value": "fixed_term",
"suggested": false
}
],
"email": null
},
"counts": {
"people": {
"new": 12,
"update": 1,
"unchanged": 0,
"problem": 2,
"blocked": 0,
"skipped": 0,
"left": 1
},
"teams": 4,
"locations": 2,
"fields": 1,
"leave": {
"new": 9,
"unchanged": 0,
"problem": 0,
"skipped": 0,
"days": 63.5
},
"balances": {
"new": 15,
"unchanged": 0,
"problem": 0,
"skipped": 0
},
"documents": {
"new": 0,
"unchanged": 0,
"problem": 0,
"skipped": 0,
"bytes": 0
},
"pay": 0,
"history": 0,
"jobs": {
"new": 0,
"problem": 0,
"skipped": 0
}
},
"problems": 2,
"report": {
"unmapped": [
"Cost center"
],
"warnings": [
"1 column is not imported: Cost center."
],
"teams": [
"Engineering",
"People"
],
"locations": [
"Berlin"
],
"fields": [
"Shirt size"
],
"blocking": [],
"storage": null
},
"progress": {
"done": 0,
"total": 0
},
"result": {
"added": 0,
"updated": 0,
"teams": 0,
"locations": 0,
"fields": 0,
"history": 0,
"pay": 0,
"pay_waiting": 0,
"leave": 0,
"balances": 0,
"documents": 0,
"problems": 0,
"payroll_notices": 0,
"numbers": 0
},
"undo": {
"available": false,
"until": null,
"undone_at": null,
"removed": 0,
"kept": []
},
"connection": null,
"started_by": {
"name": "Ana Ferreira"
},
"background": true,
"cancel_requested": false,
"error": null,
"created_at": "2026-10-12T09:00:00.000Z",
"updated_at": "2026-10-12T09:04:00.000Z",
"finished_at": null,
"expires_at": "2026-11-11T09:00:00.000Z"
}
}Discard a move#
POST/v1/migration/discardWrite
Deletes a move that is not working, with its rows; its files and the API connection made for it are removed. What it imported stays (undo it first with migration_undo, within 24 hours).
- Who can call it
- Manage key owner admin hr
- MCP tool
migration_discardon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
run_idstringrequired1–64 characters.
Returns
discardedtruerequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/migration/discard \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"run_id":"mv1"}'const res = await fetch('https://api.bizisy.com/v1/migration/discard', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"run_id": "mv1"
}),
});
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/migration/discard",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"run_id": "mv1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"discarded": true
}
}Undo a move#
POST/v1/migration/undoDestructive
Within 24 hours of an import: removes what that import created (the last import of the move, when it imported the rows left later) — the people it added (with everything recorded about them), the leave, balances and documents it added, and the teams, locations and custom fields it created that nothing else uses — unless someone changed them since (those are kept and listed). Changes to people already in Bizisy are not reverted. Runs in the background (status undoing). Only by someone signed in to Bizisy, never through an API key or AI app.
- Web app only
- Refused for API keys and connected apps. Undoing a move needs a person signed in to Bizisy.
- MCP tool
migration_undoon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
run_idstringrequired1–64 characters.
Returns
25 fields
idstringrequiredtoolstring (enum)requiredOne of:
personio,factorial,sesame,hibob,bamboohr,meta4,other.statusstring (enum)requiredOne of:
reading,mapping,checking,checked,importing,undoing,done,cancelled,failed.phase"reading" | "checking" | "importing" | "undoing"requiredThe phase at work, or the one that stopped (cancelled, failed): migration_resume runs it again.
stepstring (enum)requiredImporting: the step at work (fields, people, history, pay, leave, balances, documents, finish).
One of:
fields,people,history,pay,leave,balances,documents,finish.sourceobjectrequired3 fields
kind"file" | "text" | "api"requiredfilesobject[]required3 fields
role"people" | "timeoff" | "history"requirednamestringrequiredsizeintegerrequired
connectorstring | nullrequired
sheetsobjectrequired3 fields
peopleobject | nullrequired4 fields
namestringrequiredrowsintegerrequiredcolumnsobject[]required4 fields
headerstringrequiredtargetstring | nullrequiredWhat the column feeds (null: not imported).
confidence"exact" | "likely" | "none"requiredexact: the tool's own name for it; likely: a usual name; none: not recognised.
samplesstring[]requiredThe first values (private columns as ••• for API keys and AI apps).
mapping_setbooleanrequired
timeoffobject | nullrequired4 fields
namestringrequiredrowsintegerrequiredcolumnsobject[]required4 fields
headerstringrequiredtargetstring | nullrequiredWhat the column feeds (null: not imported).
confidence"exact" | "likely" | "none"requiredexact: the tool's own name for it; likely: a usual name; none: not recognised.
samplesstring[]requiredThe first values (private columns as ••• for API keys and AI apps).
mapping_setbooleanrequired
historyobject | nullrequiredA job-history file: one row per person and date.
4 fields
namestringrequiredrowsintegerrequiredcolumnsobject[]required4 fields
headerstringrequiredtargetstring | nullrequiredWhat the column feeds (null: not imported).
confidence"exact" | "likely" | "none"requiredexact: the tool's own name for it; likely: a usual name; none: not recognised.
samplesstring[]requiredThe first values (private columns as ••• for API keys and AI apps).
mapping_setbooleanrequired
targetsobjectrequiredWhat a column can feed: the built-in targets, field:<key> for a custom field, new:<label> for a new text field.
3 fields
peoplestring[]requiredtimeoffstring[]requiredhistorystring[]required
scopeobjectrequired4 fields
paybooleanrequiredtimeoffbooleanrequireddocumentsbooleanrequiredhistorybooleanrequired
optionsobjectrequired8 fields
leave_typesobject[]required5 fields
sourcestringrequiredcountintegerrequiredtype_idstring | nullrequiredsuggestedbooleanrequireduses_balancebooleanrequired
entitiesobject[]requiredThe old tool's legal entities and the Bizisy legal entity each maps to.
4 fields
sourcestringrequiredcountintegerrequiredentitystring | nullrequiredThe Bizisy legal entity (legal name); null: the company's default one.
suggestedbooleanrequired
location_countrystring | nullrequiredeffective_datestring | nullrequiredpay_currencystringrequiredpay_period"year" | "month" | "hour"requiredvalue_mapsobject[]requiredCodes in the file (contract types, leaving reasons, sex…) and the Bizisy value each becomes (null: left out); suggested: Bizisy's guess, not chosen yet.
5 fields
targetstringrequiredsourcestringrequiredcountintegerrequiredvaluestring | nullrequiredsuggestedbooleanrequired
emailobjectrequiredHow people without a work email in the file get one: the company's pattern, or their personal email; null: the work email is required.
4 fields (one of several shapes)
Option 1
mode"pattern"requiredpattern"first.last" | "firstlast" | "f.last" | "first"requireddomainstringrequired
Option 2
mode"personal"required
countsobjectrequired10 fields
peopleobjectrequired7 fields
newintegerrequiredupdateintegerrequiredunchangedintegerrequiredproblemintegerrequiredblockedintegerrequiredskippedintegerrequiredleftintegerrequired
teamsintegerrequiredlocationsintegerrequiredfieldsintegerrequiredleaveobjectrequired5 fields
newintegerrequiredunchangedintegerrequiredproblemintegerrequiredskippedintegerrequireddaysnumberrequired
balancesobjectrequired4 fields
newintegerrequiredunchangedintegerrequiredproblemintegerrequiredskippedintegerrequired
documentsobjectrequired5 fields
newintegerrequiredunchangedintegerrequiredproblemintegerrequiredskippedintegerrequiredbytesnumberrequired
payintegerrequiredhistoryintegerrequiredjobsobjectrequiredRows of the job-history file: recorded with their person, to fix, left out.
3 fields
newintegerrequiredproblemintegerrequiredskippedintegerrequired
problemsintegerrequiredItems to fix or skip before importing (problems and blocked rows).
reportobjectrequired7 fields
unmappedstring[]requiredwarningsstring[]requiredteamsstring[]requiredlocationsstring[]requiredfieldsstring[]requiredblockingstring[]requiredstorageobject | nullrequired4 fields
bytesnumberrequiredincluded_bytesnumberrequiredused_bytesnumberrequiredprice_cents_per_gbnumberrequired
progressobjectrequired2 fields
doneintegerrequiredtotalintegerrequired
resultobjectrequired14 fields
addedintegerrequiredupdatedintegerrequiredteamsintegerrequiredlocationsintegerrequiredfieldsintegerrequiredhistoryintegerrequiredpayintegerrequiredpay_waitingintegerPay sent for approval (Settings → Approval rules): it applies once another approver approves it.
Default
0.leaveintegerrequiredbalancesintegerrequireddocumentsintegerrequiredproblemsintegerrequiredpayroll_noticesintegerrequirednumbersintegerEmployee numbers set in Payroll.
Default
0.
undoobjectrequired5 fields
availablebooleanrequiredUndo can run now (within 24 hours of finishing, not undone yet).
untilstring | nullrequiredundone_atstring | nullrequiredremovedintegerrequiredkeptobject[]required3 fields
kindstringrequiredlabelstringrequiredreasonstringrequired
connectionobject | nullrequired2 fields
connectorstringrequiredremovedbooleanrequired
started_byobjectrequired1 field
namestringrequired
backgroundbooleanrequiredWhether the run works on the import job: follow it with migration_get.
cancel_requestedbooleanrequirederrorstring | nullrequiredcreated_atstringrequiredupdated_atstringrequiredfinished_atstring | nullrequiredexpires_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/migration/undo \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"run_id":"mv1"}'const res = await fetch('https://api.bizisy.com/v1/migration/undo', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"run_id": "mv1"
}),
});
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/migration/undo",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"run_id": "mv1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "mv1",
"tool": "personio",
"status": "undoing",
"phase": "undoing",
"step": null,
"source": {
"kind": "file",
"files": [
{
"role": "people",
"name": "personio-people.xlsx",
"size": 48211
},
{
"role": "timeoff",
"name": "absences.csv",
"size": 2104
}
],
"connector": null
},
"sheets": {
"people": {
"name": "personio-people.xlsx",
"rows": 16,
"mapping_set": true,
"columns": [
{
"header": "First name",
"target": "given_name",
"confidence": "exact",
"samples": [
"Sofia",
"Lukas"
]
},
{
"header": "Email",
"target": "work_email",
"confidence": "exact",
"samples": [
"sofia.almeida@example-company.eu",
"lukas.becker@example-company.eu"
]
},
{
"header": "Cost center",
"target": null,
"confidence": "none",
"samples": [
"CC-MAN",
"CC-ENG"
]
}
]
},
"timeoff": {
"name": "absences.csv",
"rows": 9,
"mapping_set": true,
"columns": [
{
"header": "Absence type",
"target": "leave_type",
"confidence": "exact",
"samples": [
"Paid vacation"
]
}
]
},
"history": null
},
"targets": {
"people": [
"given_name",
"family_name",
"work_email",
"title"
],
"timeoff": [
"person_email",
"leave_type",
"start",
"end"
],
"history": [
"person_id",
"from",
"title"
]
},
"scope": {
"pay": false,
"timeoff": true,
"documents": false,
"history": true
},
"options": {
"leave_types": [
{
"source": "Paid vacation",
"count": 7,
"type_id": "vacation",
"suggested": true,
"uses_balance": true
},
{
"source": "Sick leave",
"count": 2,
"type_id": null,
"suggested": false,
"uses_balance": false
}
],
"entities": [
{
"source": "Example Company GmbH",
"count": 7,
"entity": "Acme GmbH",
"suggested": true
}
],
"location_country": "PT",
"effective_date": null,
"pay_currency": "EUR",
"pay_period": "year",
"value_maps": [
{
"target": "contract_type",
"source": "CT02",
"count": 9,
"value": "fixed_term",
"suggested": false
}
],
"email": null
},
"counts": {
"people": {
"new": 12,
"update": 1,
"unchanged": 0,
"problem": 2,
"blocked": 0,
"skipped": 0,
"left": 1
},
"teams": 4,
"locations": 2,
"fields": 1,
"leave": {
"new": 9,
"unchanged": 0,
"problem": 0,
"skipped": 0,
"days": 63.5
},
"balances": {
"new": 15,
"unchanged": 0,
"problem": 0,
"skipped": 0
},
"documents": {
"new": 0,
"unchanged": 0,
"problem": 0,
"skipped": 0,
"bytes": 0
},
"pay": 0,
"history": 0,
"jobs": {
"new": 0,
"problem": 0,
"skipped": 0
}
},
"problems": 2,
"report": {
"unmapped": [
"Cost center"
],
"warnings": [
"1 column is not imported: Cost center."
],
"teams": [
"Engineering",
"People"
],
"locations": [
"Berlin"
],
"fields": [
"Shirt size"
],
"blocking": [],
"storage": null
},
"progress": {
"done": 0,
"total": 0
},
"result": {
"added": 0,
"updated": 0,
"teams": 0,
"locations": 0,
"fields": 0,
"history": 0,
"pay": 0,
"pay_waiting": 0,
"leave": 0,
"balances": 0,
"documents": 0,
"problems": 0,
"payroll_notices": 0,
"numbers": 0
},
"undo": {
"available": false,
"until": null,
"undone_at": null,
"removed": 0,
"kept": []
},
"connection": null,
"started_by": {
"name": "Ana Ferreira"
},
"background": true,
"cancel_requested": false,
"error": null,
"created_at": "2026-10-12T09:00:00.000Z",
"updated_at": "2026-10-12T09:04:00.000Z",
"finished_at": null,
"expires_at": "2026-11-11T09:00:00.000Z"
}
}Download the problems of a move#
POST/v1/migration/problems_csvRead
The rows of a move with problems as CSV text (row, name, column, problem), to fix in the source and upload again. Values are written so a spreadsheet never runs them as formulas.
- Who can call it
- Manage key owner admin hr
- MCP tool
migration_problems_csvon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
run_idstringrequired1–64 characters.
Returns
filenamestringrequiredcsvstringrequiredrowsintegerrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/migration/problems_csv \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"run_id":"mv1"}'const res = await fetch('https://api.bizisy.com/v1/migration/problems_csv', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"run_id": "mv1"
}),
});
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/migration/problems_csv",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"run_id": "mv1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"filename": "bizisy-move-problems-2026-10-12.csv",
"csv": "row,kind,name,column,problem\n11,person,Pierre Martin,Email,Use a valid email address.\n",
"rows": 1
}
}List the tools a company can move from#
POST/v1/migration/toolsRead
The HR and payroll tools a company can move people from, whether each is read through its API, and whether the company saved its column choices for it (the next move matches them at once).
- Who can call it
- Manage key owner admin hr
- MCP tool
migration_toolson HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
toolsobject[]required4 fields
idstring (enum)requiredOne of:
personio,factorial,sesame,hibob,bamboohr,meta4,other.namestringrequiredapibooleanrequiredsavedbooleanrequiredThe company's column choices for this tool are remembered.
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/migration/tools \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/migration/tools', {
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/migration/tools",
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": {
"tools": [
{
"id": "personio",
"name": "Personio",
"api": true,
"saved": false
},
{
"id": "meta4",
"name": "Meta4 PeopleNet",
"api": false,
"saved": true
},
{
"id": "other",
"name": "Other tool or spreadsheet",
"api": false,
"saved": false
}
]
}
}Preview a move to another tool#
POST/v1/migration/exports.previewRead
What a move to another tool would contain, without building it: the files (in the import format of Personio, Factorial, Sesame HR, HiBob, BambooHR, or a CSV/XLSX for any tool), counts, values the tool does not know and what they become, and what it can't import from a file. Owners and admins, in the web app only (never an API key or AI app).
- Web app only
- Refused for API keys and connected apps. Moving to another tool happens in the Bizisy web app.
- MCP tool
migration_exports_previewon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
tool"personio" | "factorial" | "sesame" | "hibob" | "bamboohr" | "any"requiredinclude_paybooleanPay history (private): only with the pay tier.
Default
false.include_documentsbooleanPeople's document files, in a folder per person, with an index.
Default
false.include_leftbooleanPeople who left, with their leaving date.
Default
true.
Returns
9 fields
tool"personio" | "factorial" | "sesame" | "hibob" | "bamboohr" | "any"requiredlanguagestringrequiredcountsobjectrequired12 fields
peopleintegerrequiredleftintegerrequiredhistoryintegerrequiredteamsintegerrequiredlocationsintegerrequiredentitiesintegerrequiredfieldsintegerrequiredleaveintegerrequiredbalancesintegerrequireddocumentsintegerrequireddocuments_bytesnumberrequireddocuments_left_outintegerrequired
payobjectrequired2 fields
availablebooleanrequiredpeopleintegerrequired
filesobject[]required2 fields
namestringrequiredwhatstringrequired
warningsstring[]requiredValues the destination does not know, and what they become.
notesstring[]requiredWhat the destination can't import from a file (e.g. no time-off import): included as a readable CSV anyway.
help_urlstring | nullrequiredmax_bytesintegerrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/migration/exports.preview \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"tool": "any",
"include_pay": true,
"include_documents": true,
"include_left": false
}'const res = await fetch('https://api.bizisy.com/v1/migration/exports.preview', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"tool": "any",
"include_pay": true,
"include_documents": true,
"include_left": false
}),
});
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/migration/exports.preview",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"tool": "any",
"include_pay": True,
"include_documents": True,
"include_left": False,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"tool": "any",
"language": "en",
"counts": {
"people": 23,
"left": 4,
"history": 41,
"teams": 5,
"locations": 2,
"entities": 1,
"fields": 3,
"leave": 120,
"balances": 23,
"documents": 0,
"documents_bytes": 0,
"documents_left_out": 0
},
"pay": {
"available": true,
"people": 21
},
"files": [
{
"name": "README.txt",
"what": "How to import each file, step by step"
},
{
"name": "personio-employees.xlsx",
"what": "People and their current job, in Personio’s import columns"
}
],
"warnings": [
"3 people have the employment type \"intern\": exported as \"Intern\" (Personio’s own word)."
],
"notes": [],
"help_url": "https://support.personio.de/hc/en-us/articles/115001324149",
"max_bytes": 100000000
}
}Export for another tool#
POST/v1/migration/exports.startWrite
Builds the files to move the company to another tool in the background, then emails the person who asked that they are ready (never the files). The download is a zip through Bizisy storage, its link short-lived; it stays 7 days. At most 5 a day and one at a time. reason: an optional note on why (kept with the export). The company's data stays in Bizisy as before. Owners and admins, in the app only: API keys and AI assistants are refused.
- Web app only
- Refused for API keys and connected apps. Moving to another tool happens in the Bizisy web app.
- MCP tool
migration_exports_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
tool"personio" | "factorial" | "sesame" | "hibob" | "bamboohr" | "any"requiredinclude_paybooleanPay history (private): only with the pay tier.
Default
false.include_documentsbooleanPeople's document files, in a folder per person, with an index.
Default
false.include_leftbooleanPeople who left, with their leaving date.
Default
true.reasonstringUp to 1000 characters.
Returns
11 fields
idstringrequiredtool"personio" | "factorial" | "sesame" | "hibob" | "bamboohr" | "any"requiredstatus"building" | "ready" | "failed" | "removed"requiredoptionsobjectrequired3 fields
paybooleanrequireddocumentsbooleanrequiredleftbooleanrequired
countsobjectrequired6 fields
peopleintegerrequiredhistoryintegerrequiredleaveintegerrequiredbalancesintegerrequireddocumentsintegerrequireddocuments_left_outintegerrequired
warningsstring[]requiredfileobject | nullrequired2 fields
namestringrequiredsizeintegerrequired
errorstring | nullrequiredcreated_atstringrequiredready_atstring | nullrequireddownload_untilstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/migration/exports.start \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"tool": "bamboohr",
"include_pay": false,
"include_documents": true,
"include_left": true,
"reason": "We need payroll in the same tool."
}'const res = await fetch('https://api.bizisy.com/v1/migration/exports.start', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"tool": "bamboohr",
"include_pay": false,
"include_documents": true,
"include_left": true,
"reason": "We need payroll in the same tool."
}),
});
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/migration/exports.start",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"tool": "bamboohr",
"include_pay": False,
"include_documents": True,
"include_left": True,
"reason": "We need payroll in the same tool.",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "ex1",
"tool": "bamboohr",
"status": "building",
"options": {
"pay": false,
"documents": false,
"left": true
},
"counts": {
"people": 0,
"history": 0,
"leave": 0,
"balances": 0,
"documents": 0,
"documents_left_out": 0
},
"warnings": [],
"file": null,
"error": null,
"created_at": "2026-10-12T09:00:00.000Z",
"ready_at": null,
"download_until": null
}
}Get an export for another tool#
POST/v1/migration/exports.getRead
One export: building, ready (download it with migration_exports_download until download_until), failed or removed. Owners and admins, in the app only: API keys and AI assistants are refused.
- Web app only
- Refused for API keys and connected apps. Moving to another tool happens in the Bizisy web app.
- MCP tool
migration_exports_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
export_idstringrequired1–64 characters.
Returns
11 fields
idstringrequiredtool"personio" | "factorial" | "sesame" | "hibob" | "bamboohr" | "any"requiredstatus"building" | "ready" | "failed" | "removed"requiredoptionsobjectrequired3 fields
paybooleanrequireddocumentsbooleanrequiredleftbooleanrequired
countsobjectrequired6 fields
peopleintegerrequiredhistoryintegerrequiredleaveintegerrequiredbalancesintegerrequireddocumentsintegerrequireddocuments_left_outintegerrequired
warningsstring[]requiredfileobject | nullrequired2 fields
namestringrequiredsizeintegerrequired
errorstring | nullrequiredcreated_atstringrequiredready_atstring | nullrequireddownload_untilstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/migration/exports.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"export_id":"ex1"}'const res = await fetch('https://api.bizisy.com/v1/migration/exports.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"export_id": "ex1"
}),
});
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/migration/exports.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"export_id": "ex1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "ex1",
"tool": "personio",
"status": "ready",
"options": {
"pay": false,
"documents": false,
"left": true
},
"counts": {
"people": 27,
"history": 41,
"leave": 120,
"balances": 23,
"documents": 0,
"documents_left_out": 0
},
"warnings": [],
"file": {
"name": "bizisy-for-personio-2026-10-12.zip",
"size": 48211
},
"error": null,
"created_at": "2026-10-12T09:00:00.000Z",
"ready_at": "2026-10-12T09:01:00.000Z",
"download_until": "2026-10-19T09:01:00.000Z"
}
}List exports for another tool#
POST/v1/migration/exports.listRead
The company's exports for other tools of the last 30 days, newest first. Owners and admins, in the app only: API keys and AI assistants are refused.
- Web app only
- Refused for API keys and connected apps. Moving to another tool happens in the Bizisy web app.
- MCP tool
migration_exports_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
An array of objects with 11 fields
An array of objects:
idstringrequiredtool"personio" | "factorial" | "sesame" | "hibob" | "bamboohr" | "any"requiredstatus"building" | "ready" | "failed" | "removed"requiredoptionsobjectrequired3 fields
paybooleanrequireddocumentsbooleanrequiredleftbooleanrequired
countsobjectrequired6 fields
peopleintegerrequiredhistoryintegerrequiredleaveintegerrequiredbalancesintegerrequireddocumentsintegerrequireddocuments_left_outintegerrequired
warningsstring[]requiredfileobject | nullrequired2 fields
namestringrequiredsizeintegerrequired
errorstring | nullrequiredcreated_atstringrequiredready_atstring | nullrequireddownload_untilstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/migration/exports.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/migration/exports.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/migration/exports.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": "ex1",
"tool": "personio",
"status": "ready",
"options": {
"pay": false,
"documents": false,
"left": true
},
"counts": {
"people": 27,
"history": 41,
"leave": 120,
"balances": 23,
"documents": 0,
"documents_left_out": 0
},
"warnings": [],
"file": {
"name": "bizisy-for-personio-2026-10-12.zip",
"size": 48211
},
"error": null,
"created_at": "2026-10-12T09:00:00.000Z",
"ready_at": "2026-10-12T09:01:00.000Z",
"download_until": "2026-10-19T09:01:00.000Z"
}
]
}Download an export for another tool#
POST/v1/migration/exports.downloadWrite
A short-lived link (5 minutes) to download a ready export as a zip. Each download is recorded in Activity. Owners and admins, in the app only: API keys and AI assistants are refused.
- Web app only
- Refused for API keys and connected apps. Moving to another tool happens in the Bizisy web app.
- MCP tool
migration_exports_downloadon 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
export_idstringrequired1–64 characters.
Returns
urlstring | nullrequirednull on a dry run.
expires_atstring | nullrequiredfile_namestringrequiredsizeintegerrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/migration/exports.download \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"export_id":"ex1"}'const res = await fetch('https://api.bizisy.com/v1/migration/exports.download', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"export_id": "ex1"
}),
});
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/migration/exports.download",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"export_id": "ex1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"url": "https://storage.example/download/ex1",
"expires_at": "2026-10-12T09:06:00.000Z",
"file_name": "bizisy-for-personio-2026-10-12.zip",
"size": 48211
}
}Delete an export for another tool#
POST/v1/migration/exports.removeDestructive
Deletes an export's file now (it is deleted after 7 days anyway). The company's data in Bizisy is not touched. Owners and admins, in the app only: API keys and AI assistants are refused.
- Web app only
- Refused for API keys and connected apps. Moving to another tool happens in the Bizisy web app.
- MCP tool
migration_exports_removeon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
export_idstringrequired1–64 characters.
Returns
11 fields
idstringrequiredtool"personio" | "factorial" | "sesame" | "hibob" | "bamboohr" | "any"requiredstatus"building" | "ready" | "failed" | "removed"requiredoptionsobjectrequired3 fields
paybooleanrequireddocumentsbooleanrequiredleftbooleanrequired
countsobjectrequired6 fields
peopleintegerrequiredhistoryintegerrequiredleaveintegerrequiredbalancesintegerrequireddocumentsintegerrequireddocuments_left_outintegerrequired
warningsstring[]requiredfileobject | nullrequired2 fields
namestringrequiredsizeintegerrequired
errorstring | nullrequiredcreated_atstringrequiredready_atstring | nullrequireddownload_untilstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/migration/exports.remove \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"export_id":"ex1"}'const res = await fetch('https://api.bizisy.com/v1/migration/exports.remove', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"export_id": "ex1"
}),
});
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/migration/exports.remove",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"export_id": "ex1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "ex1",
"tool": "personio",
"status": "removed",
"options": {
"pay": false,
"documents": false,
"left": true
},
"counts": {
"people": 27,
"history": 41,
"leave": 120,
"balances": 23,
"documents": 0,
"documents_left_out": 0
},
"warnings": [],
"file": null,
"error": null,
"created_at": "2026-10-12T09:00:00.000Z",
"ready_at": "2026-10-12T09:01:00.000Z",
"download_until": "2026-10-19T09:01:00.000Z"
}
}Something missing or wrong on this page? Write to hello@bizisy.com.