Skip to content

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_upload on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • namestringrequired

    1–200 characters.

  • sizeintegerrequired

    From 0 to 20971520.

  • sha256stringrequired

    Pattern ^[0-9a-f]{64}$.

  • kind"csv" | "xlsx"required

Returns

  • file_idstringrequired
  • uploadobject | nullrequired
    4 fields
    • urlstringrequired
    • method"PUT"required
    • headersobjectrequired
    • resumablefalserequired
  • expires_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
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"
}'
Response
{
  "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_start on HR Assistant
Preview
?dry_run=true runs 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)required

    One of: personio, factorial, sesame, hibob, bamboohr, meta4, other.

  • csvstring

    1–1000000 characters.

  • filesobject[]

    1–3 items.

    2 fields
    • file_idstringrequired

      1–64 characters.

    • role"people" | "timeoff" | "history"required
  • connectiontrue
  • namestring

    Up to 200 characters.

Returns

25 fields
  • idstringrequired
  • toolstring (enum)required

    One of: personio, factorial, sesame, hibob, bamboohr, meta4, other.

  • statusstring (enum)required

    One of: reading, mapping, checking, checked, importing, undoing, done, cancelled, failed.

  • phase"reading" | "checking" | "importing" | "undoing"required

    The phase at work, or the one that stopped (cancelled, failed): migration_resume runs it again.

  • stepstring (enum)required

    Importing: the step at work (fields, people, history, pay, leave, balances, documents, finish).

    One of: fields, people, history, pay, leave, balances, documents, finish.

  • sourceobjectrequired
    3 fields
    • kind"file" | "text" | "api"required
    • filesobject[]required
      3 fields
      • role"people" | "timeoff" | "history"required
      • namestringrequired
      • sizeintegerrequired
    • connectorstring | nullrequired
  • sheetsobjectrequired
    3 fields
    • peopleobject | nullrequired
      4 fields
      • namestringrequired
      • rowsintegerrequired
      • columnsobject[]required
        4 fields
        • headerstringrequired
        • targetstring | nullrequired

          What the column feeds (null: not imported).

        • confidence"exact" | "likely" | "none"required

          exact: the tool's own name for it; likely: a usual name; none: not recognised.

        • samplesstring[]required

          The first values (private columns as ••• for API keys and AI apps).

      • mapping_setbooleanrequired
    • timeoffobject | nullrequired
      4 fields
      • namestringrequired
      • rowsintegerrequired
      • columnsobject[]required
        4 fields
        • headerstringrequired
        • targetstring | nullrequired

          What the column feeds (null: not imported).

        • confidence"exact" | "likely" | "none"required

          exact: the tool's own name for it; likely: a usual name; none: not recognised.

        • samplesstring[]required

          The first values (private columns as ••• for API keys and AI apps).

      • mapping_setbooleanrequired
    • historyobject | nullrequired

      A job-history file: one row per person and date.

      4 fields
      • namestringrequired
      • rowsintegerrequired
      • columnsobject[]required
        4 fields
        • headerstringrequired
        • targetstring | nullrequired

          What the column feeds (null: not imported).

        • confidence"exact" | "likely" | "none"required

          exact: the tool's own name for it; likely: a usual name; none: not recognised.

        • samplesstring[]required

          The first values (private columns as ••• for API keys and AI apps).

      • mapping_setbooleanrequired
  • targetsobjectrequired

    What a column can feed: the built-in targets, field:<key> for a custom field, new:<label> for a new text field.

    3 fields
    • peoplestring[]required
    • timeoffstring[]required
    • historystring[]required
  • scopeobjectrequired
    4 fields
    • paybooleanrequired
    • timeoffbooleanrequired
    • documentsbooleanrequired
    • historybooleanrequired
  • optionsobjectrequired
    8 fields
    • leave_typesobject[]required
      5 fields
      • sourcestringrequired
      • countintegerrequired
      • type_idstring | nullrequired
      • suggestedbooleanrequired
      • uses_balancebooleanrequired
    • entitiesobject[]required

      The old tool's legal entities and the Bizisy legal entity each maps to.

      4 fields
      • sourcestringrequired
      • countintegerrequired
      • entitystring | nullrequired

        The Bizisy legal entity (legal name); null: the company's default one.

      • suggestedbooleanrequired
    • location_countrystring | nullrequired
    • effective_datestring | nullrequired
    • pay_currencystringrequired
    • pay_period"year" | "month" | "hour"required
    • value_mapsobject[]required

      Codes 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
      • targetstringrequired
      • sourcestringrequired
      • countintegerrequired
      • valuestring | nullrequired
      • suggestedbooleanrequired
    • emailobjectrequired

      How 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"required
      • pattern"first.last" | "firstlast" | "f.last" | "first"required
      • domainstringrequired

      Option 2

      • mode"personal"required
  • countsobjectrequired
    10 fields
    • peopleobjectrequired
      7 fields
      • newintegerrequired
      • updateintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • blockedintegerrequired
      • skippedintegerrequired
      • leftintegerrequired
    • teamsintegerrequired
    • locationsintegerrequired
    • fieldsintegerrequired
    • leaveobjectrequired
      5 fields
      • newintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
      • daysnumberrequired
    • balancesobjectrequired
      4 fields
      • newintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
    • documentsobjectrequired
      5 fields
      • newintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
      • bytesnumberrequired
    • payintegerrequired
    • historyintegerrequired
    • jobsobjectrequired

      Rows of the job-history file: recorded with their person, to fix, left out.

      3 fields
      • newintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
  • problemsintegerrequired

    Items to fix or skip before importing (problems and blocked rows).

  • reportobjectrequired
    7 fields
    • unmappedstring[]required
    • warningsstring[]required
    • teamsstring[]required
    • locationsstring[]required
    • fieldsstring[]required
    • blockingstring[]required
    • storageobject | nullrequired
      4 fields
      • bytesnumberrequired
      • included_bytesnumberrequired
      • used_bytesnumberrequired
      • price_cents_per_gbnumberrequired
  • progressobjectrequired
    2 fields
    • doneintegerrequired
    • totalintegerrequired
  • resultobjectrequired
    14 fields
    • addedintegerrequired
    • updatedintegerrequired
    • teamsintegerrequired
    • locationsintegerrequired
    • fieldsintegerrequired
    • historyintegerrequired
    • payintegerrequired
    • pay_waitinginteger

      Pay sent for approval (Settings → Approval rules): it applies once another approver approves it.

      Default 0.

    • leaveintegerrequired
    • balancesintegerrequired
    • documentsintegerrequired
    • problemsintegerrequired
    • payroll_noticesintegerrequired
    • numbersinteger

      Employee numbers set in Payroll.

      Default 0.

  • undoobjectrequired
    5 fields
    • availablebooleanrequired

      Undo can run now (within 24 hours of finishing, not undone yet).

    • untilstring | nullrequired
    • undone_atstring | nullrequired
    • removedintegerrequired
    • keptobject[]required
      3 fields
      • kindstringrequired
      • labelstringrequired
      • reasonstringrequired
  • connectionobject | nullrequired
    2 fields
    • connectorstringrequired
    • removedbooleanrequired
  • started_byobjectrequired
    1 field
    • namestringrequired
  • backgroundbooleanrequired

    Whether the run works on the import job: follow it with migration_get.

  • cancel_requestedbooleanrequired
  • errorstring | nullrequired
  • created_atstringrequired
  • updated_atstringrequired
  • finished_atstring | nullrequired
  • expires_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
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"
    }
  ]
}'
Response
{
  "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_check on HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–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"required
    • sourcestringrequired

      Up to 100 characters.

    • valuestring | nullrequired

      Up to 40 characters.

  • emailobject

    People 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"required
    • pattern"first.last" | "firstlast" | "f.last" | "first"required
    • domainstringrequired

      Up to 200 characters.

    Option 2

    • mode"personal"required
  • scopeobject

    pay (default false; in Bizisy only), time off and documents (default true).

    3 fields
    • payboolean
    • timeoffboolean
    • documentsboolean
  • 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
    • sourcestringrequired

      Up to 60 characters.

    • type_idstring | nullrequired

      Up 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
    • sourcestringrequired

      Up to 200 characters.

    • entitystring | nullrequired

      Up to 200 characters.

  • location_countrystring | null

    The country of locations the move creates (default the company's).

    Pattern ^[A-Z]{2}$.

  • effective_datestring | null

    The day job changes of people already in Bizisy take effect (default today).

    Pattern ^\d{4}-\d{2}-\d{2}$.

  • pay_currencystring

    Pattern ^[A-Z]{3}$.

  • pay_period"year" | "month" | "hour"

Returns

25 fields
  • idstringrequired
  • toolstring (enum)required

    One of: personio, factorial, sesame, hibob, bamboohr, meta4, other.

  • statusstring (enum)required

    One of: reading, mapping, checking, checked, importing, undoing, done, cancelled, failed.

  • phase"reading" | "checking" | "importing" | "undoing"required

    The phase at work, or the one that stopped (cancelled, failed): migration_resume runs it again.

  • stepstring (enum)required

    Importing: the step at work (fields, people, history, pay, leave, balances, documents, finish).

    One of: fields, people, history, pay, leave, balances, documents, finish.

  • sourceobjectrequired
    3 fields
    • kind"file" | "text" | "api"required
    • filesobject[]required
      3 fields
      • role"people" | "timeoff" | "history"required
      • namestringrequired
      • sizeintegerrequired
    • connectorstring | nullrequired
  • sheetsobjectrequired
    3 fields
    • peopleobject | nullrequired
      4 fields
      • namestringrequired
      • rowsintegerrequired
      • columnsobject[]required
        4 fields
        • headerstringrequired
        • targetstring | nullrequired

          What the column feeds (null: not imported).

        • confidence"exact" | "likely" | "none"required

          exact: the tool's own name for it; likely: a usual name; none: not recognised.

        • samplesstring[]required

          The first values (private columns as ••• for API keys and AI apps).

      • mapping_setbooleanrequired
    • timeoffobject | nullrequired
      4 fields
      • namestringrequired
      • rowsintegerrequired
      • columnsobject[]required
        4 fields
        • headerstringrequired
        • targetstring | nullrequired

          What the column feeds (null: not imported).

        • confidence"exact" | "likely" | "none"required

          exact: the tool's own name for it; likely: a usual name; none: not recognised.

        • samplesstring[]required

          The first values (private columns as ••• for API keys and AI apps).

      • mapping_setbooleanrequired
    • historyobject | nullrequired

      A job-history file: one row per person and date.

      4 fields
      • namestringrequired
      • rowsintegerrequired
      • columnsobject[]required
        4 fields
        • headerstringrequired
        • targetstring | nullrequired

          What the column feeds (null: not imported).

        • confidence"exact" | "likely" | "none"required

          exact: the tool's own name for it; likely: a usual name; none: not recognised.

        • samplesstring[]required

          The first values (private columns as ••• for API keys and AI apps).

      • mapping_setbooleanrequired
  • targetsobjectrequired

    What a column can feed: the built-in targets, field:<key> for a custom field, new:<label> for a new text field.

    3 fields
    • peoplestring[]required
    • timeoffstring[]required
    • historystring[]required
  • scopeobjectrequired
    4 fields
    • paybooleanrequired
    • timeoffbooleanrequired
    • documentsbooleanrequired
    • historybooleanrequired
  • optionsobjectrequired
    8 fields
    • leave_typesobject[]required
      5 fields
      • sourcestringrequired
      • countintegerrequired
      • type_idstring | nullrequired
      • suggestedbooleanrequired
      • uses_balancebooleanrequired
    • entitiesobject[]required

      The old tool's legal entities and the Bizisy legal entity each maps to.

      4 fields
      • sourcestringrequired
      • countintegerrequired
      • entitystring | nullrequired

        The Bizisy legal entity (legal name); null: the company's default one.

      • suggestedbooleanrequired
    • location_countrystring | nullrequired
    • effective_datestring | nullrequired
    • pay_currencystringrequired
    • pay_period"year" | "month" | "hour"required
    • value_mapsobject[]required

      Codes 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
      • targetstringrequired
      • sourcestringrequired
      • countintegerrequired
      • valuestring | nullrequired
      • suggestedbooleanrequired
    • emailobjectrequired

      How 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"required
      • pattern"first.last" | "firstlast" | "f.last" | "first"required
      • domainstringrequired

      Option 2

      • mode"personal"required
  • countsobjectrequired
    10 fields
    • peopleobjectrequired
      7 fields
      • newintegerrequired
      • updateintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • blockedintegerrequired
      • skippedintegerrequired
      • leftintegerrequired
    • teamsintegerrequired
    • locationsintegerrequired
    • fieldsintegerrequired
    • leaveobjectrequired
      5 fields
      • newintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
      • daysnumberrequired
    • balancesobjectrequired
      4 fields
      • newintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
    • documentsobjectrequired
      5 fields
      • newintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
      • bytesnumberrequired
    • payintegerrequired
    • historyintegerrequired
    • jobsobjectrequired

      Rows of the job-history file: recorded with their person, to fix, left out.

      3 fields
      • newintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
  • problemsintegerrequired

    Items to fix or skip before importing (problems and blocked rows).

  • reportobjectrequired
    7 fields
    • unmappedstring[]required
    • warningsstring[]required
    • teamsstring[]required
    • locationsstring[]required
    • fieldsstring[]required
    • blockingstring[]required
    • storageobject | nullrequired
      4 fields
      • bytesnumberrequired
      • included_bytesnumberrequired
      • used_bytesnumberrequired
      • price_cents_per_gbnumberrequired
  • progressobjectrequired
    2 fields
    • doneintegerrequired
    • totalintegerrequired
  • resultobjectrequired
    14 fields
    • addedintegerrequired
    • updatedintegerrequired
    • teamsintegerrequired
    • locationsintegerrequired
    • fieldsintegerrequired
    • historyintegerrequired
    • payintegerrequired
    • pay_waitinginteger

      Pay sent for approval (Settings → Approval rules): it applies once another approver approves it.

      Default 0.

    • leaveintegerrequired
    • balancesintegerrequired
    • documentsintegerrequired
    • problemsintegerrequired
    • payroll_noticesintegerrequired
    • numbersinteger

      Employee numbers set in Payroll.

      Default 0.

  • undoobjectrequired
    5 fields
    • availablebooleanrequired

      Undo can run now (within 24 hours of finishing, not undone yet).

    • untilstring | nullrequired
    • undone_atstring | nullrequired
    • removedintegerrequired
    • keptobject[]required
      3 fields
      • kindstringrequired
      • labelstringrequired
      • reasonstringrequired
  • connectionobject | nullrequired
    2 fields
    • connectorstringrequired
    • removedbooleanrequired
  • started_byobjectrequired
    1 field
    • namestringrequired
  • backgroundbooleanrequired

    Whether the run works on the import job: follow it with migration_get.

  • cancel_requestedbooleanrequired
  • errorstring | nullrequired
  • created_atstringrequired
  • updated_atstringrequired
  • finished_atstring | nullrequired
  • expires_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
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"
}'
Response
{
  "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_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • run_idstringrequired

    1–64 characters.

Returns

25 fields
  • idstringrequired
  • toolstring (enum)required

    One of: personio, factorial, sesame, hibob, bamboohr, meta4, other.

  • statusstring (enum)required

    One of: reading, mapping, checking, checked, importing, undoing, done, cancelled, failed.

  • phase"reading" | "checking" | "importing" | "undoing"required

    The phase at work, or the one that stopped (cancelled, failed): migration_resume runs it again.

  • stepstring (enum)required

    Importing: the step at work (fields, people, history, pay, leave, balances, documents, finish).

    One of: fields, people, history, pay, leave, balances, documents, finish.

  • sourceobjectrequired
    3 fields
    • kind"file" | "text" | "api"required
    • filesobject[]required
      3 fields
      • role"people" | "timeoff" | "history"required
      • namestringrequired
      • sizeintegerrequired
    • connectorstring | nullrequired
  • sheetsobjectrequired
    3 fields
    • peopleobject | nullrequired
      4 fields
      • namestringrequired
      • rowsintegerrequired
      • columnsobject[]required
        4 fields
        • headerstringrequired
        • targetstring | nullrequired

          What the column feeds (null: not imported).

        • confidence"exact" | "likely" | "none"required

          exact: the tool's own name for it; likely: a usual name; none: not recognised.

        • samplesstring[]required

          The first values (private columns as ••• for API keys and AI apps).

      • mapping_setbooleanrequired
    • timeoffobject | nullrequired
      4 fields
      • namestringrequired
      • rowsintegerrequired
      • columnsobject[]required
        4 fields
        • headerstringrequired
        • targetstring | nullrequired

          What the column feeds (null: not imported).

        • confidence"exact" | "likely" | "none"required

          exact: the tool's own name for it; likely: a usual name; none: not recognised.

        • samplesstring[]required

          The first values (private columns as ••• for API keys and AI apps).

      • mapping_setbooleanrequired
    • historyobject | nullrequired

      A job-history file: one row per person and date.

      4 fields
      • namestringrequired
      • rowsintegerrequired
      • columnsobject[]required
        4 fields
        • headerstringrequired
        • targetstring | nullrequired

          What the column feeds (null: not imported).

        • confidence"exact" | "likely" | "none"required

          exact: the tool's own name for it; likely: a usual name; none: not recognised.

        • samplesstring[]required

          The first values (private columns as ••• for API keys and AI apps).

      • mapping_setbooleanrequired
  • targetsobjectrequired

    What a column can feed: the built-in targets, field:<key> for a custom field, new:<label> for a new text field.

    3 fields
    • peoplestring[]required
    • timeoffstring[]required
    • historystring[]required
  • scopeobjectrequired
    4 fields
    • paybooleanrequired
    • timeoffbooleanrequired
    • documentsbooleanrequired
    • historybooleanrequired
  • optionsobjectrequired
    8 fields
    • leave_typesobject[]required
      5 fields
      • sourcestringrequired
      • countintegerrequired
      • type_idstring | nullrequired
      • suggestedbooleanrequired
      • uses_balancebooleanrequired
    • entitiesobject[]required

      The old tool's legal entities and the Bizisy legal entity each maps to.

      4 fields
      • sourcestringrequired
      • countintegerrequired
      • entitystring | nullrequired

        The Bizisy legal entity (legal name); null: the company's default one.

      • suggestedbooleanrequired
    • location_countrystring | nullrequired
    • effective_datestring | nullrequired
    • pay_currencystringrequired
    • pay_period"year" | "month" | "hour"required
    • value_mapsobject[]required

      Codes 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
      • targetstringrequired
      • sourcestringrequired
      • countintegerrequired
      • valuestring | nullrequired
      • suggestedbooleanrequired
    • emailobjectrequired

      How 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"required
      • pattern"first.last" | "firstlast" | "f.last" | "first"required
      • domainstringrequired

      Option 2

      • mode"personal"required
  • countsobjectrequired
    10 fields
    • peopleobjectrequired
      7 fields
      • newintegerrequired
      • updateintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • blockedintegerrequired
      • skippedintegerrequired
      • leftintegerrequired
    • teamsintegerrequired
    • locationsintegerrequired
    • fieldsintegerrequired
    • leaveobjectrequired
      5 fields
      • newintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
      • daysnumberrequired
    • balancesobjectrequired
      4 fields
      • newintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
    • documentsobjectrequired
      5 fields
      • newintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
      • bytesnumberrequired
    • payintegerrequired
    • historyintegerrequired
    • jobsobjectrequired

      Rows of the job-history file: recorded with their person, to fix, left out.

      3 fields
      • newintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
  • problemsintegerrequired

    Items to fix or skip before importing (problems and blocked rows).

  • reportobjectrequired
    7 fields
    • unmappedstring[]required
    • warningsstring[]required
    • teamsstring[]required
    • locationsstring[]required
    • fieldsstring[]required
    • blockingstring[]required
    • storageobject | nullrequired
      4 fields
      • bytesnumberrequired
      • included_bytesnumberrequired
      • used_bytesnumberrequired
      • price_cents_per_gbnumberrequired
  • progressobjectrequired
    2 fields
    • doneintegerrequired
    • totalintegerrequired
  • resultobjectrequired
    14 fields
    • addedintegerrequired
    • updatedintegerrequired
    • teamsintegerrequired
    • locationsintegerrequired
    • fieldsintegerrequired
    • historyintegerrequired
    • payintegerrequired
    • pay_waitinginteger

      Pay sent for approval (Settings → Approval rules): it applies once another approver approves it.

      Default 0.

    • leaveintegerrequired
    • balancesintegerrequired
    • documentsintegerrequired
    • problemsintegerrequired
    • payroll_noticesintegerrequired
    • numbersinteger

      Employee numbers set in Payroll.

      Default 0.

  • undoobjectrequired
    5 fields
    • availablebooleanrequired

      Undo can run now (within 24 hours of finishing, not undone yet).

    • untilstring | nullrequired
    • undone_atstring | nullrequired
    • removedintegerrequired
    • keptobject[]required
      3 fields
      • kindstringrequired
      • labelstringrequired
      • reasonstringrequired
  • connectionobject | nullrequired
    2 fields
    • connectorstringrequired
    • removedbooleanrequired
  • started_byobjectrequired
    1 field
    • namestringrequired
  • backgroundbooleanrequired

    Whether the run works on the import job: follow it with migration_get.

  • cancel_requestedbooleanrequired
  • errorstring | nullrequired
  • created_atstringrequired
  • updated_atstringrequired
  • finished_atstring | nullrequired
  • expires_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/migration/get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"run_id":"mv1"}'
Response
{
  "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_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

An array of objects with 25 fields

An array of objects:

  • idstringrequired
  • toolstring (enum)required

    One of: personio, factorial, sesame, hibob, bamboohr, meta4, other.

  • statusstring (enum)required

    One of: reading, mapping, checking, checked, importing, undoing, done, cancelled, failed.

  • phase"reading" | "checking" | "importing" | "undoing"required

    The phase at work, or the one that stopped (cancelled, failed): migration_resume runs it again.

  • stepstring (enum)required

    Importing: the step at work (fields, people, history, pay, leave, balances, documents, finish).

    One of: fields, people, history, pay, leave, balances, documents, finish.

  • sourceobjectrequired
    3 fields
    • kind"file" | "text" | "api"required
    • filesobject[]required
      3 fields
      • role"people" | "timeoff" | "history"required
      • namestringrequired
      • sizeintegerrequired
    • connectorstring | nullrequired
  • sheetsobjectrequired
    3 fields
    • peopleobject | nullrequired
      4 fields
      • namestringrequired
      • rowsintegerrequired
      • columnsobject[]required
        4 fields
        • headerstringrequired
        • targetstring | nullrequired

          What the column feeds (null: not imported).

        • confidence"exact" | "likely" | "none"required

          exact: the tool's own name for it; likely: a usual name; none: not recognised.

        • samplesstring[]required

          The first values (private columns as ••• for API keys and AI apps).

      • mapping_setbooleanrequired
    • timeoffobject | nullrequired
      4 fields
      • namestringrequired
      • rowsintegerrequired
      • columnsobject[]required
        4 fields
        • headerstringrequired
        • targetstring | nullrequired

          What the column feeds (null: not imported).

        • confidence"exact" | "likely" | "none"required

          exact: the tool's own name for it; likely: a usual name; none: not recognised.

        • samplesstring[]required

          The first values (private columns as ••• for API keys and AI apps).

      • mapping_setbooleanrequired
    • historyobject | nullrequired

      A job-history file: one row per person and date.

      4 fields
      • namestringrequired
      • rowsintegerrequired
      • columnsobject[]required
        4 fields
        • headerstringrequired
        • targetstring | nullrequired

          What the column feeds (null: not imported).

        • confidence"exact" | "likely" | "none"required

          exact: the tool's own name for it; likely: a usual name; none: not recognised.

        • samplesstring[]required

          The first values (private columns as ••• for API keys and AI apps).

      • mapping_setbooleanrequired
  • targetsobjectrequired

    What a column can feed: the built-in targets, field:<key> for a custom field, new:<label> for a new text field.

    3 fields
    • peoplestring[]required
    • timeoffstring[]required
    • historystring[]required
  • scopeobjectrequired
    4 fields
    • paybooleanrequired
    • timeoffbooleanrequired
    • documentsbooleanrequired
    • historybooleanrequired
  • optionsobjectrequired
    8 fields
    • leave_typesobject[]required
      5 fields
      • sourcestringrequired
      • countintegerrequired
      • type_idstring | nullrequired
      • suggestedbooleanrequired
      • uses_balancebooleanrequired
    • entitiesobject[]required

      The old tool's legal entities and the Bizisy legal entity each maps to.

      4 fields
      • sourcestringrequired
      • countintegerrequired
      • entitystring | nullrequired

        The Bizisy legal entity (legal name); null: the company's default one.

      • suggestedbooleanrequired
    • location_countrystring | nullrequired
    • effective_datestring | nullrequired
    • pay_currencystringrequired
    • pay_period"year" | "month" | "hour"required
    • value_mapsobject[]required

      Codes 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
      • targetstringrequired
      • sourcestringrequired
      • countintegerrequired
      • valuestring | nullrequired
      • suggestedbooleanrequired
    • emailobjectrequired

      How 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"required
      • pattern"first.last" | "firstlast" | "f.last" | "first"required
      • domainstringrequired

      Option 2

      • mode"personal"required
  • countsobjectrequired
    10 fields
    • peopleobjectrequired
      7 fields
      • newintegerrequired
      • updateintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • blockedintegerrequired
      • skippedintegerrequired
      • leftintegerrequired
    • teamsintegerrequired
    • locationsintegerrequired
    • fieldsintegerrequired
    • leaveobjectrequired
      5 fields
      • newintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
      • daysnumberrequired
    • balancesobjectrequired
      4 fields
      • newintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
    • documentsobjectrequired
      5 fields
      • newintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
      • bytesnumberrequired
    • payintegerrequired
    • historyintegerrequired
    • jobsobjectrequired

      Rows of the job-history file: recorded with their person, to fix, left out.

      3 fields
      • newintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
  • problemsintegerrequired

    Items to fix or skip before importing (problems and blocked rows).

  • reportobjectrequired
    7 fields
    • unmappedstring[]required
    • warningsstring[]required
    • teamsstring[]required
    • locationsstring[]required
    • fieldsstring[]required
    • blockingstring[]required
    • storageobject | nullrequired
      4 fields
      • bytesnumberrequired
      • included_bytesnumberrequired
      • used_bytesnumberrequired
      • price_cents_per_gbnumberrequired
  • progressobjectrequired
    2 fields
    • doneintegerrequired
    • totalintegerrequired
  • resultobjectrequired
    14 fields
    • addedintegerrequired
    • updatedintegerrequired
    • teamsintegerrequired
    • locationsintegerrequired
    • fieldsintegerrequired
    • historyintegerrequired
    • payintegerrequired
    • pay_waitinginteger

      Pay sent for approval (Settings → Approval rules): it applies once another approver approves it.

      Default 0.

    • leaveintegerrequired
    • balancesintegerrequired
    • documentsintegerrequired
    • problemsintegerrequired
    • payroll_noticesintegerrequired
    • numbersinteger

      Employee numbers set in Payroll.

      Default 0.

  • undoobjectrequired
    5 fields
    • availablebooleanrequired

      Undo can run now (within 24 hours of finishing, not undone yet).

    • untilstring | nullrequired
    • undone_atstring | nullrequired
    • removedintegerrequired
    • keptobject[]required
      3 fields
      • kindstringrequired
      • labelstringrequired
      • reasonstringrequired
  • connectionobject | nullrequired
    2 fields
    • connectorstringrequired
    • removedbooleanrequired
  • started_byobjectrequired
    1 field
    • namestringrequired
  • backgroundbooleanrequired

    Whether the run works on the import job: follow it with migration_get.

  • cancel_requestedbooleanrequired
  • errorstring | nullrequired
  • created_atstringrequired
  • updated_atstringrequired
  • finished_atstring | nullrequired
  • expires_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/migration/list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "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_items on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • run_idstringrequired

    1–64 characters.

  • kind"person" | "leave" | "balance" | "document" | "job"

    Default "person".

  • filterstring (enum)

    One of: all, fix, new, update, unchanged, skipped, applied. Default "all".

  • afterinteger

    At least 0. Default 0.

  • limitinteger

    From 1 to 100. Default 50.

Returns

  • itemsobject[]required
    15 fields
    • idstringrequired
    • kind"person" | "leave" | "balance" | "document" | "job"required
    • nintegerrequired
    • sheet"people" | "timeoff" | "history" | "api"required
    • labelstringrequired
    • emailstringrequired
    • outcomestring (enum)required

      One of: pending, new, update, unchanged, problem, blocked, skipped.

    • appliedbooleanrequired
    • skipbooleanrequired
    • bizisy_idstring | nullrequired
    • createdbooleanrequired
    • cellsstring[] | nullrequired

      The row as in the file, by header cell (null once applied; private and pay cells hidden from API keys and AI apps).

    • changesobject[]required
      4 fields
      • fieldstringrequired
      • beforestring | nullrequired
      • afterstring | nullrequired
      • hiddenboolean
    • problemsobject[]required
      5 fields
      • columnstring | nullrequired
      • targetstring | nullrequired
      • messagestringrequired
      • fix"edit" | "pick" | "skip"required
      • optionsstring[]
    • notestring | nullrequired
  • nextinteger | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
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}'
Response
{
  "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_items on HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–64 characters.

  • itemsobject[]required

    1–100 items.

    3 fields
    • idstringrequired

      1–200 characters.

    • setobject[]

      Up to 300 items.

      2 fields
      • columnintegerrequired

        From 0 to 299.

      • valuestringrequired

        Up to 2000 characters.

    • skipboolean

Returns

25 fields
  • idstringrequired
  • toolstring (enum)required

    One of: personio, factorial, sesame, hibob, bamboohr, meta4, other.

  • statusstring (enum)required

    One of: reading, mapping, checking, checked, importing, undoing, done, cancelled, failed.

  • phase"reading" | "checking" | "importing" | "undoing"required

    The phase at work, or the one that stopped (cancelled, failed): migration_resume runs it again.

  • stepstring (enum)required

    Importing: the step at work (fields, people, history, pay, leave, balances, documents, finish).

    One of: fields, people, history, pay, leave, balances, documents, finish.

  • sourceobjectrequired
    3 fields
    • kind"file" | "text" | "api"required
    • filesobject[]required
      3 fields
      • role"people" | "timeoff" | "history"required
      • namestringrequired
      • sizeintegerrequired
    • connectorstring | nullrequired
  • sheetsobjectrequired
    3 fields
    • peopleobject | nullrequired
      4 fields
      • namestringrequired
      • rowsintegerrequired
      • columnsobject[]required
        4 fields
        • headerstringrequired
        • targetstring | nullrequired

          What the column feeds (null: not imported).

        • confidence"exact" | "likely" | "none"required

          exact: the tool's own name for it; likely: a usual name; none: not recognised.

        • samplesstring[]required

          The first values (private columns as ••• for API keys and AI apps).

      • mapping_setbooleanrequired
    • timeoffobject | nullrequired
      4 fields
      • namestringrequired
      • rowsintegerrequired
      • columnsobject[]required
        4 fields
        • headerstringrequired
        • targetstring | nullrequired

          What the column feeds (null: not imported).

        • confidence"exact" | "likely" | "none"required

          exact: the tool's own name for it; likely: a usual name; none: not recognised.

        • samplesstring[]required

          The first values (private columns as ••• for API keys and AI apps).

      • mapping_setbooleanrequired
    • historyobject | nullrequired

      A job-history file: one row per person and date.

      4 fields
      • namestringrequired
      • rowsintegerrequired
      • columnsobject[]required
        4 fields
        • headerstringrequired
        • targetstring | nullrequired

          What the column feeds (null: not imported).

        • confidence"exact" | "likely" | "none"required

          exact: the tool's own name for it; likely: a usual name; none: not recognised.

        • samplesstring[]required

          The first values (private columns as ••• for API keys and AI apps).

      • mapping_setbooleanrequired
  • targetsobjectrequired

    What a column can feed: the built-in targets, field:<key> for a custom field, new:<label> for a new text field.

    3 fields
    • peoplestring[]required
    • timeoffstring[]required
    • historystring[]required
  • scopeobjectrequired
    4 fields
    • paybooleanrequired
    • timeoffbooleanrequired
    • documentsbooleanrequired
    • historybooleanrequired
  • optionsobjectrequired
    8 fields
    • leave_typesobject[]required
      5 fields
      • sourcestringrequired
      • countintegerrequired
      • type_idstring | nullrequired
      • suggestedbooleanrequired
      • uses_balancebooleanrequired
    • entitiesobject[]required

      The old tool's legal entities and the Bizisy legal entity each maps to.

      4 fields
      • sourcestringrequired
      • countintegerrequired
      • entitystring | nullrequired

        The Bizisy legal entity (legal name); null: the company's default one.

      • suggestedbooleanrequired
    • location_countrystring | nullrequired
    • effective_datestring | nullrequired
    • pay_currencystringrequired
    • pay_period"year" | "month" | "hour"required
    • value_mapsobject[]required

      Codes 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
      • targetstringrequired
      • sourcestringrequired
      • countintegerrequired
      • valuestring | nullrequired
      • suggestedbooleanrequired
    • emailobjectrequired

      How 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"required
      • pattern"first.last" | "firstlast" | "f.last" | "first"required
      • domainstringrequired

      Option 2

      • mode"personal"required
  • countsobjectrequired
    10 fields
    • peopleobjectrequired
      7 fields
      • newintegerrequired
      • updateintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • blockedintegerrequired
      • skippedintegerrequired
      • leftintegerrequired
    • teamsintegerrequired
    • locationsintegerrequired
    • fieldsintegerrequired
    • leaveobjectrequired
      5 fields
      • newintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
      • daysnumberrequired
    • balancesobjectrequired
      4 fields
      • newintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
    • documentsobjectrequired
      5 fields
      • newintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
      • bytesnumberrequired
    • payintegerrequired
    • historyintegerrequired
    • jobsobjectrequired

      Rows of the job-history file: recorded with their person, to fix, left out.

      3 fields
      • newintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
  • problemsintegerrequired

    Items to fix or skip before importing (problems and blocked rows).

  • reportobjectrequired
    7 fields
    • unmappedstring[]required
    • warningsstring[]required
    • teamsstring[]required
    • locationsstring[]required
    • fieldsstring[]required
    • blockingstring[]required
    • storageobject | nullrequired
      4 fields
      • bytesnumberrequired
      • included_bytesnumberrequired
      • used_bytesnumberrequired
      • price_cents_per_gbnumberrequired
  • progressobjectrequired
    2 fields
    • doneintegerrequired
    • totalintegerrequired
  • resultobjectrequired
    14 fields
    • addedintegerrequired
    • updatedintegerrequired
    • teamsintegerrequired
    • locationsintegerrequired
    • fieldsintegerrequired
    • historyintegerrequired
    • payintegerrequired
    • pay_waitinginteger

      Pay sent for approval (Settings → Approval rules): it applies once another approver approves it.

      Default 0.

    • leaveintegerrequired
    • balancesintegerrequired
    • documentsintegerrequired
    • problemsintegerrequired
    • payroll_noticesintegerrequired
    • numbersinteger

      Employee numbers set in Payroll.

      Default 0.

  • undoobjectrequired
    5 fields
    • availablebooleanrequired

      Undo can run now (within 24 hours of finishing, not undone yet).

    • untilstring | nullrequired
    • undone_atstring | nullrequired
    • removedintegerrequired
    • keptobject[]required
      3 fields
      • kindstringrequired
      • labelstringrequired
      • reasonstringrequired
  • connectionobject | nullrequired
    2 fields
    • connectorstringrequired
    • removedbooleanrequired
  • started_byobjectrequired
    1 field
    • namestringrequired
  • backgroundbooleanrequired

    Whether the run works on the import job: follow it with migration_get.

  • cancel_requestedbooleanrequired
  • errorstring | nullrequired
  • created_atstringrequired
  • updated_atstringrequired
  • finished_atstring | nullrequired
  • expires_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
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
    }
  ]
}'
Response
{
  "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_import on HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–64 characters.

Returns

25 fields
  • idstringrequired
  • toolstring (enum)required

    One of: personio, factorial, sesame, hibob, bamboohr, meta4, other.

  • statusstring (enum)required

    One of: reading, mapping, checking, checked, importing, undoing, done, cancelled, failed.

  • phase"reading" | "checking" | "importing" | "undoing"required

    The phase at work, or the one that stopped (cancelled, failed): migration_resume runs it again.

  • stepstring (enum)required

    Importing: the step at work (fields, people, history, pay, leave, balances, documents, finish).

    One of: fields, people, history, pay, leave, balances, documents, finish.

  • sourceobjectrequired
    3 fields
    • kind"file" | "text" | "api"required
    • filesobject[]required
      3 fields
      • role"people" | "timeoff" | "history"required
      • namestringrequired
      • sizeintegerrequired
    • connectorstring | nullrequired
  • sheetsobjectrequired
    3 fields
    • peopleobject | nullrequired
      4 fields
      • namestringrequired
      • rowsintegerrequired
      • columnsobject[]required
        4 fields
        • headerstringrequired
        • targetstring | nullrequired

          What the column feeds (null: not imported).

        • confidence"exact" | "likely" | "none"required

          exact: the tool's own name for it; likely: a usual name; none: not recognised.

        • samplesstring[]required

          The first values (private columns as ••• for API keys and AI apps).

      • mapping_setbooleanrequired
    • timeoffobject | nullrequired
      4 fields
      • namestringrequired
      • rowsintegerrequired
      • columnsobject[]required
        4 fields
        • headerstringrequired
        • targetstring | nullrequired

          What the column feeds (null: not imported).

        • confidence"exact" | "likely" | "none"required

          exact: the tool's own name for it; likely: a usual name; none: not recognised.

        • samplesstring[]required

          The first values (private columns as ••• for API keys and AI apps).

      • mapping_setbooleanrequired
    • historyobject | nullrequired

      A job-history file: one row per person and date.

      4 fields
      • namestringrequired
      • rowsintegerrequired
      • columnsobject[]required
        4 fields
        • headerstringrequired
        • targetstring | nullrequired

          What the column feeds (null: not imported).

        • confidence"exact" | "likely" | "none"required

          exact: the tool's own name for it; likely: a usual name; none: not recognised.

        • samplesstring[]required

          The first values (private columns as ••• for API keys and AI apps).

      • mapping_setbooleanrequired
  • targetsobjectrequired

    What a column can feed: the built-in targets, field:<key> for a custom field, new:<label> for a new text field.

    3 fields
    • peoplestring[]required
    • timeoffstring[]required
    • historystring[]required
  • scopeobjectrequired
    4 fields
    • paybooleanrequired
    • timeoffbooleanrequired
    • documentsbooleanrequired
    • historybooleanrequired
  • optionsobjectrequired
    8 fields
    • leave_typesobject[]required
      5 fields
      • sourcestringrequired
      • countintegerrequired
      • type_idstring | nullrequired
      • suggestedbooleanrequired
      • uses_balancebooleanrequired
    • entitiesobject[]required

      The old tool's legal entities and the Bizisy legal entity each maps to.

      4 fields
      • sourcestringrequired
      • countintegerrequired
      • entitystring | nullrequired

        The Bizisy legal entity (legal name); null: the company's default one.

      • suggestedbooleanrequired
    • location_countrystring | nullrequired
    • effective_datestring | nullrequired
    • pay_currencystringrequired
    • pay_period"year" | "month" | "hour"required
    • value_mapsobject[]required

      Codes 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
      • targetstringrequired
      • sourcestringrequired
      • countintegerrequired
      • valuestring | nullrequired
      • suggestedbooleanrequired
    • emailobjectrequired

      How 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"required
      • pattern"first.last" | "firstlast" | "f.last" | "first"required
      • domainstringrequired

      Option 2

      • mode"personal"required
  • countsobjectrequired
    10 fields
    • peopleobjectrequired
      7 fields
      • newintegerrequired
      • updateintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • blockedintegerrequired
      • skippedintegerrequired
      • leftintegerrequired
    • teamsintegerrequired
    • locationsintegerrequired
    • fieldsintegerrequired
    • leaveobjectrequired
      5 fields
      • newintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
      • daysnumberrequired
    • balancesobjectrequired
      4 fields
      • newintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
    • documentsobjectrequired
      5 fields
      • newintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
      • bytesnumberrequired
    • payintegerrequired
    • historyintegerrequired
    • jobsobjectrequired

      Rows of the job-history file: recorded with their person, to fix, left out.

      3 fields
      • newintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
  • problemsintegerrequired

    Items to fix or skip before importing (problems and blocked rows).

  • reportobjectrequired
    7 fields
    • unmappedstring[]required
    • warningsstring[]required
    • teamsstring[]required
    • locationsstring[]required
    • fieldsstring[]required
    • blockingstring[]required
    • storageobject | nullrequired
      4 fields
      • bytesnumberrequired
      • included_bytesnumberrequired
      • used_bytesnumberrequired
      • price_cents_per_gbnumberrequired
  • progressobjectrequired
    2 fields
    • doneintegerrequired
    • totalintegerrequired
  • resultobjectrequired
    14 fields
    • addedintegerrequired
    • updatedintegerrequired
    • teamsintegerrequired
    • locationsintegerrequired
    • fieldsintegerrequired
    • historyintegerrequired
    • payintegerrequired
    • pay_waitinginteger

      Pay sent for approval (Settings → Approval rules): it applies once another approver approves it.

      Default 0.

    • leaveintegerrequired
    • balancesintegerrequired
    • documentsintegerrequired
    • problemsintegerrequired
    • payroll_noticesintegerrequired
    • numbersinteger

      Employee numbers set in Payroll.

      Default 0.

  • undoobjectrequired
    5 fields
    • availablebooleanrequired

      Undo can run now (within 24 hours of finishing, not undone yet).

    • untilstring | nullrequired
    • undone_atstring | nullrequired
    • removedintegerrequired
    • keptobject[]required
      3 fields
      • kindstringrequired
      • labelstringrequired
      • reasonstringrequired
  • connectionobject | nullrequired
    2 fields
    • connectorstringrequired
    • removedbooleanrequired
  • started_byobjectrequired
    1 field
    • namestringrequired
  • backgroundbooleanrequired

    Whether the run works on the import job: follow it with migration_get.

  • cancel_requestedbooleanrequired
  • errorstring | nullrequired
  • created_atstringrequired
  • updated_atstringrequired
  • finished_atstring | nullrequired
  • expires_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
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"}'
Response
{
  "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_cancel on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • run_idstringrequired

    1–64 characters.

Returns

25 fields
  • idstringrequired
  • toolstring (enum)required

    One of: personio, factorial, sesame, hibob, bamboohr, meta4, other.

  • statusstring (enum)required

    One of: reading, mapping, checking, checked, importing, undoing, done, cancelled, failed.

  • phase"reading" | "checking" | "importing" | "undoing"required

    The phase at work, or the one that stopped (cancelled, failed): migration_resume runs it again.

  • stepstring (enum)required

    Importing: the step at work (fields, people, history, pay, leave, balances, documents, finish).

    One of: fields, people, history, pay, leave, balances, documents, finish.

  • sourceobjectrequired
    3 fields
    • kind"file" | "text" | "api"required
    • filesobject[]required
      3 fields
      • role"people" | "timeoff" | "history"required
      • namestringrequired
      • sizeintegerrequired
    • connectorstring | nullrequired
  • sheetsobjectrequired
    3 fields
    • peopleobject | nullrequired
      4 fields
      • namestringrequired
      • rowsintegerrequired
      • columnsobject[]required
        4 fields
        • headerstringrequired
        • targetstring | nullrequired

          What the column feeds (null: not imported).

        • confidence"exact" | "likely" | "none"required

          exact: the tool's own name for it; likely: a usual name; none: not recognised.

        • samplesstring[]required

          The first values (private columns as ••• for API keys and AI apps).

      • mapping_setbooleanrequired
    • timeoffobject | nullrequired
      4 fields
      • namestringrequired
      • rowsintegerrequired
      • columnsobject[]required
        4 fields
        • headerstringrequired
        • targetstring | nullrequired

          What the column feeds (null: not imported).

        • confidence"exact" | "likely" | "none"required

          exact: the tool's own name for it; likely: a usual name; none: not recognised.

        • samplesstring[]required

          The first values (private columns as ••• for API keys and AI apps).

      • mapping_setbooleanrequired
    • historyobject | nullrequired

      A job-history file: one row per person and date.

      4 fields
      • namestringrequired
      • rowsintegerrequired
      • columnsobject[]required
        4 fields
        • headerstringrequired
        • targetstring | nullrequired

          What the column feeds (null: not imported).

        • confidence"exact" | "likely" | "none"required

          exact: the tool's own name for it; likely: a usual name; none: not recognised.

        • samplesstring[]required

          The first values (private columns as ••• for API keys and AI apps).

      • mapping_setbooleanrequired
  • targetsobjectrequired

    What a column can feed: the built-in targets, field:<key> for a custom field, new:<label> for a new text field.

    3 fields
    • peoplestring[]required
    • timeoffstring[]required
    • historystring[]required
  • scopeobjectrequired
    4 fields
    • paybooleanrequired
    • timeoffbooleanrequired
    • documentsbooleanrequired
    • historybooleanrequired
  • optionsobjectrequired
    8 fields
    • leave_typesobject[]required
      5 fields
      • sourcestringrequired
      • countintegerrequired
      • type_idstring | nullrequired
      • suggestedbooleanrequired
      • uses_balancebooleanrequired
    • entitiesobject[]required

      The old tool's legal entities and the Bizisy legal entity each maps to.

      4 fields
      • sourcestringrequired
      • countintegerrequired
      • entitystring | nullrequired

        The Bizisy legal entity (legal name); null: the company's default one.

      • suggestedbooleanrequired
    • location_countrystring | nullrequired
    • effective_datestring | nullrequired
    • pay_currencystringrequired
    • pay_period"year" | "month" | "hour"required
    • value_mapsobject[]required

      Codes 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
      • targetstringrequired
      • sourcestringrequired
      • countintegerrequired
      • valuestring | nullrequired
      • suggestedbooleanrequired
    • emailobjectrequired

      How 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"required
      • pattern"first.last" | "firstlast" | "f.last" | "first"required
      • domainstringrequired

      Option 2

      • mode"personal"required
  • countsobjectrequired
    10 fields
    • peopleobjectrequired
      7 fields
      • newintegerrequired
      • updateintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • blockedintegerrequired
      • skippedintegerrequired
      • leftintegerrequired
    • teamsintegerrequired
    • locationsintegerrequired
    • fieldsintegerrequired
    • leaveobjectrequired
      5 fields
      • newintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
      • daysnumberrequired
    • balancesobjectrequired
      4 fields
      • newintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
    • documentsobjectrequired
      5 fields
      • newintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
      • bytesnumberrequired
    • payintegerrequired
    • historyintegerrequired
    • jobsobjectrequired

      Rows of the job-history file: recorded with their person, to fix, left out.

      3 fields
      • newintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
  • problemsintegerrequired

    Items to fix or skip before importing (problems and blocked rows).

  • reportobjectrequired
    7 fields
    • unmappedstring[]required
    • warningsstring[]required
    • teamsstring[]required
    • locationsstring[]required
    • fieldsstring[]required
    • blockingstring[]required
    • storageobject | nullrequired
      4 fields
      • bytesnumberrequired
      • included_bytesnumberrequired
      • used_bytesnumberrequired
      • price_cents_per_gbnumberrequired
  • progressobjectrequired
    2 fields
    • doneintegerrequired
    • totalintegerrequired
  • resultobjectrequired
    14 fields
    • addedintegerrequired
    • updatedintegerrequired
    • teamsintegerrequired
    • locationsintegerrequired
    • fieldsintegerrequired
    • historyintegerrequired
    • payintegerrequired
    • pay_waitinginteger

      Pay sent for approval (Settings → Approval rules): it applies once another approver approves it.

      Default 0.

    • leaveintegerrequired
    • balancesintegerrequired
    • documentsintegerrequired
    • problemsintegerrequired
    • payroll_noticesintegerrequired
    • numbersinteger

      Employee numbers set in Payroll.

      Default 0.

  • undoobjectrequired
    5 fields
    • availablebooleanrequired

      Undo can run now (within 24 hours of finishing, not undone yet).

    • untilstring | nullrequired
    • undone_atstring | nullrequired
    • removedintegerrequired
    • keptobject[]required
      3 fields
      • kindstringrequired
      • labelstringrequired
      • reasonstringrequired
  • connectionobject | nullrequired
    2 fields
    • connectorstringrequired
    • removedbooleanrequired
  • started_byobjectrequired
    1 field
    • namestringrequired
  • backgroundbooleanrequired

    Whether the run works on the import job: follow it with migration_get.

  • cancel_requestedbooleanrequired
  • errorstring | nullrequired
  • created_atstringrequired
  • updated_atstringrequired
  • finished_atstring | nullrequired
  • expires_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
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"}'
Response
{
  "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_resume on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • run_idstringrequired

    1–64 characters.

Returns

25 fields
  • idstringrequired
  • toolstring (enum)required

    One of: personio, factorial, sesame, hibob, bamboohr, meta4, other.

  • statusstring (enum)required

    One of: reading, mapping, checking, checked, importing, undoing, done, cancelled, failed.

  • phase"reading" | "checking" | "importing" | "undoing"required

    The phase at work, or the one that stopped (cancelled, failed): migration_resume runs it again.

  • stepstring (enum)required

    Importing: the step at work (fields, people, history, pay, leave, balances, documents, finish).

    One of: fields, people, history, pay, leave, balances, documents, finish.

  • sourceobjectrequired
    3 fields
    • kind"file" | "text" | "api"required
    • filesobject[]required
      3 fields
      • role"people" | "timeoff" | "history"required
      • namestringrequired
      • sizeintegerrequired
    • connectorstring | nullrequired
  • sheetsobjectrequired
    3 fields
    • peopleobject | nullrequired
      4 fields
      • namestringrequired
      • rowsintegerrequired
      • columnsobject[]required
        4 fields
        • headerstringrequired
        • targetstring | nullrequired

          What the column feeds (null: not imported).

        • confidence"exact" | "likely" | "none"required

          exact: the tool's own name for it; likely: a usual name; none: not recognised.

        • samplesstring[]required

          The first values (private columns as ••• for API keys and AI apps).

      • mapping_setbooleanrequired
    • timeoffobject | nullrequired
      4 fields
      • namestringrequired
      • rowsintegerrequired
      • columnsobject[]required
        4 fields
        • headerstringrequired
        • targetstring | nullrequired

          What the column feeds (null: not imported).

        • confidence"exact" | "likely" | "none"required

          exact: the tool's own name for it; likely: a usual name; none: not recognised.

        • samplesstring[]required

          The first values (private columns as ••• for API keys and AI apps).

      • mapping_setbooleanrequired
    • historyobject | nullrequired

      A job-history file: one row per person and date.

      4 fields
      • namestringrequired
      • rowsintegerrequired
      • columnsobject[]required
        4 fields
        • headerstringrequired
        • targetstring | nullrequired

          What the column feeds (null: not imported).

        • confidence"exact" | "likely" | "none"required

          exact: the tool's own name for it; likely: a usual name; none: not recognised.

        • samplesstring[]required

          The first values (private columns as ••• for API keys and AI apps).

      • mapping_setbooleanrequired
  • targetsobjectrequired

    What a column can feed: the built-in targets, field:<key> for a custom field, new:<label> for a new text field.

    3 fields
    • peoplestring[]required
    • timeoffstring[]required
    • historystring[]required
  • scopeobjectrequired
    4 fields
    • paybooleanrequired
    • timeoffbooleanrequired
    • documentsbooleanrequired
    • historybooleanrequired
  • optionsobjectrequired
    8 fields
    • leave_typesobject[]required
      5 fields
      • sourcestringrequired
      • countintegerrequired
      • type_idstring | nullrequired
      • suggestedbooleanrequired
      • uses_balancebooleanrequired
    • entitiesobject[]required

      The old tool's legal entities and the Bizisy legal entity each maps to.

      4 fields
      • sourcestringrequired
      • countintegerrequired
      • entitystring | nullrequired

        The Bizisy legal entity (legal name); null: the company's default one.

      • suggestedbooleanrequired
    • location_countrystring | nullrequired
    • effective_datestring | nullrequired
    • pay_currencystringrequired
    • pay_period"year" | "month" | "hour"required
    • value_mapsobject[]required

      Codes 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
      • targetstringrequired
      • sourcestringrequired
      • countintegerrequired
      • valuestring | nullrequired
      • suggestedbooleanrequired
    • emailobjectrequired

      How 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"required
      • pattern"first.last" | "firstlast" | "f.last" | "first"required
      • domainstringrequired

      Option 2

      • mode"personal"required
  • countsobjectrequired
    10 fields
    • peopleobjectrequired
      7 fields
      • newintegerrequired
      • updateintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • blockedintegerrequired
      • skippedintegerrequired
      • leftintegerrequired
    • teamsintegerrequired
    • locationsintegerrequired
    • fieldsintegerrequired
    • leaveobjectrequired
      5 fields
      • newintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
      • daysnumberrequired
    • balancesobjectrequired
      4 fields
      • newintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
    • documentsobjectrequired
      5 fields
      • newintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
      • bytesnumberrequired
    • payintegerrequired
    • historyintegerrequired
    • jobsobjectrequired

      Rows of the job-history file: recorded with their person, to fix, left out.

      3 fields
      • newintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
  • problemsintegerrequired

    Items to fix or skip before importing (problems and blocked rows).

  • reportobjectrequired
    7 fields
    • unmappedstring[]required
    • warningsstring[]required
    • teamsstring[]required
    • locationsstring[]required
    • fieldsstring[]required
    • blockingstring[]required
    • storageobject | nullrequired
      4 fields
      • bytesnumberrequired
      • included_bytesnumberrequired
      • used_bytesnumberrequired
      • price_cents_per_gbnumberrequired
  • progressobjectrequired
    2 fields
    • doneintegerrequired
    • totalintegerrequired
  • resultobjectrequired
    14 fields
    • addedintegerrequired
    • updatedintegerrequired
    • teamsintegerrequired
    • locationsintegerrequired
    • fieldsintegerrequired
    • historyintegerrequired
    • payintegerrequired
    • pay_waitinginteger

      Pay sent for approval (Settings → Approval rules): it applies once another approver approves it.

      Default 0.

    • leaveintegerrequired
    • balancesintegerrequired
    • documentsintegerrequired
    • problemsintegerrequired
    • payroll_noticesintegerrequired
    • numbersinteger

      Employee numbers set in Payroll.

      Default 0.

  • undoobjectrequired
    5 fields
    • availablebooleanrequired

      Undo can run now (within 24 hours of finishing, not undone yet).

    • untilstring | nullrequired
    • undone_atstring | nullrequired
    • removedintegerrequired
    • keptobject[]required
      3 fields
      • kindstringrequired
      • labelstringrequired
      • reasonstringrequired
  • connectionobject | nullrequired
    2 fields
    • connectorstringrequired
    • removedbooleanrequired
  • started_byobjectrequired
    1 field
    • namestringrequired
  • backgroundbooleanrequired

    Whether the run works on the import job: follow it with migration_get.

  • cancel_requestedbooleanrequired
  • errorstring | nullrequired
  • created_atstringrequired
  • updated_atstringrequired
  • finished_atstring | nullrequired
  • expires_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
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"}'
Response
{
  "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_discard on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • run_idstringrequired

    1–64 characters.

Returns

  • discardedtruerequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
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"}'
Response
{
  "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_undo on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • run_idstringrequired

    1–64 characters.

Returns

25 fields
  • idstringrequired
  • toolstring (enum)required

    One of: personio, factorial, sesame, hibob, bamboohr, meta4, other.

  • statusstring (enum)required

    One of: reading, mapping, checking, checked, importing, undoing, done, cancelled, failed.

  • phase"reading" | "checking" | "importing" | "undoing"required

    The phase at work, or the one that stopped (cancelled, failed): migration_resume runs it again.

  • stepstring (enum)required

    Importing: the step at work (fields, people, history, pay, leave, balances, documents, finish).

    One of: fields, people, history, pay, leave, balances, documents, finish.

  • sourceobjectrequired
    3 fields
    • kind"file" | "text" | "api"required
    • filesobject[]required
      3 fields
      • role"people" | "timeoff" | "history"required
      • namestringrequired
      • sizeintegerrequired
    • connectorstring | nullrequired
  • sheetsobjectrequired
    3 fields
    • peopleobject | nullrequired
      4 fields
      • namestringrequired
      • rowsintegerrequired
      • columnsobject[]required
        4 fields
        • headerstringrequired
        • targetstring | nullrequired

          What the column feeds (null: not imported).

        • confidence"exact" | "likely" | "none"required

          exact: the tool's own name for it; likely: a usual name; none: not recognised.

        • samplesstring[]required

          The first values (private columns as ••• for API keys and AI apps).

      • mapping_setbooleanrequired
    • timeoffobject | nullrequired
      4 fields
      • namestringrequired
      • rowsintegerrequired
      • columnsobject[]required
        4 fields
        • headerstringrequired
        • targetstring | nullrequired

          What the column feeds (null: not imported).

        • confidence"exact" | "likely" | "none"required

          exact: the tool's own name for it; likely: a usual name; none: not recognised.

        • samplesstring[]required

          The first values (private columns as ••• for API keys and AI apps).

      • mapping_setbooleanrequired
    • historyobject | nullrequired

      A job-history file: one row per person and date.

      4 fields
      • namestringrequired
      • rowsintegerrequired
      • columnsobject[]required
        4 fields
        • headerstringrequired
        • targetstring | nullrequired

          What the column feeds (null: not imported).

        • confidence"exact" | "likely" | "none"required

          exact: the tool's own name for it; likely: a usual name; none: not recognised.

        • samplesstring[]required

          The first values (private columns as ••• for API keys and AI apps).

      • mapping_setbooleanrequired
  • targetsobjectrequired

    What a column can feed: the built-in targets, field:<key> for a custom field, new:<label> for a new text field.

    3 fields
    • peoplestring[]required
    • timeoffstring[]required
    • historystring[]required
  • scopeobjectrequired
    4 fields
    • paybooleanrequired
    • timeoffbooleanrequired
    • documentsbooleanrequired
    • historybooleanrequired
  • optionsobjectrequired
    8 fields
    • leave_typesobject[]required
      5 fields
      • sourcestringrequired
      • countintegerrequired
      • type_idstring | nullrequired
      • suggestedbooleanrequired
      • uses_balancebooleanrequired
    • entitiesobject[]required

      The old tool's legal entities and the Bizisy legal entity each maps to.

      4 fields
      • sourcestringrequired
      • countintegerrequired
      • entitystring | nullrequired

        The Bizisy legal entity (legal name); null: the company's default one.

      • suggestedbooleanrequired
    • location_countrystring | nullrequired
    • effective_datestring | nullrequired
    • pay_currencystringrequired
    • pay_period"year" | "month" | "hour"required
    • value_mapsobject[]required

      Codes 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
      • targetstringrequired
      • sourcestringrequired
      • countintegerrequired
      • valuestring | nullrequired
      • suggestedbooleanrequired
    • emailobjectrequired

      How 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"required
      • pattern"first.last" | "firstlast" | "f.last" | "first"required
      • domainstringrequired

      Option 2

      • mode"personal"required
  • countsobjectrequired
    10 fields
    • peopleobjectrequired
      7 fields
      • newintegerrequired
      • updateintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • blockedintegerrequired
      • skippedintegerrequired
      • leftintegerrequired
    • teamsintegerrequired
    • locationsintegerrequired
    • fieldsintegerrequired
    • leaveobjectrequired
      5 fields
      • newintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
      • daysnumberrequired
    • balancesobjectrequired
      4 fields
      • newintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
    • documentsobjectrequired
      5 fields
      • newintegerrequired
      • unchangedintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
      • bytesnumberrequired
    • payintegerrequired
    • historyintegerrequired
    • jobsobjectrequired

      Rows of the job-history file: recorded with their person, to fix, left out.

      3 fields
      • newintegerrequired
      • problemintegerrequired
      • skippedintegerrequired
  • problemsintegerrequired

    Items to fix or skip before importing (problems and blocked rows).

  • reportobjectrequired
    7 fields
    • unmappedstring[]required
    • warningsstring[]required
    • teamsstring[]required
    • locationsstring[]required
    • fieldsstring[]required
    • blockingstring[]required
    • storageobject | nullrequired
      4 fields
      • bytesnumberrequired
      • included_bytesnumberrequired
      • used_bytesnumberrequired
      • price_cents_per_gbnumberrequired
  • progressobjectrequired
    2 fields
    • doneintegerrequired
    • totalintegerrequired
  • resultobjectrequired
    14 fields
    • addedintegerrequired
    • updatedintegerrequired
    • teamsintegerrequired
    • locationsintegerrequired
    • fieldsintegerrequired
    • historyintegerrequired
    • payintegerrequired
    • pay_waitinginteger

      Pay sent for approval (Settings → Approval rules): it applies once another approver approves it.

      Default 0.

    • leaveintegerrequired
    • balancesintegerrequired
    • documentsintegerrequired
    • problemsintegerrequired
    • payroll_noticesintegerrequired
    • numbersinteger

      Employee numbers set in Payroll.

      Default 0.

  • undoobjectrequired
    5 fields
    • availablebooleanrequired

      Undo can run now (within 24 hours of finishing, not undone yet).

    • untilstring | nullrequired
    • undone_atstring | nullrequired
    • removedintegerrequired
    • keptobject[]required
      3 fields
      • kindstringrequired
      • labelstringrequired
      • reasonstringrequired
  • connectionobject | nullrequired
    2 fields
    • connectorstringrequired
    • removedbooleanrequired
  • started_byobjectrequired
    1 field
    • namestringrequired
  • backgroundbooleanrequired

    Whether the run works on the import job: follow it with migration_get.

  • cancel_requestedbooleanrequired
  • errorstring | nullrequired
  • created_atstringrequired
  • updated_atstringrequired
  • finished_atstring | nullrequired
  • expires_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
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"}'
Response
{
  "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_csv on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • run_idstringrequired

    1–64 characters.

Returns

  • filenamestringrequired
  • csvstringrequired
  • rowsintegerrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/migration/problems_csv \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"run_id":"mv1"}'
Response
{
  "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_tools on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • toolsobject[]required
    4 fields
    • idstring (enum)required

      One of: personio, factorial, sesame, hibob, bamboohr, meta4, other.

    • namestringrequired
    • apibooleanrequired
    • savedbooleanrequired

      The company's column choices for this tool are remembered.

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/migration/tools \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "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_preview on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • tool"personio" | "factorial" | "sesame" | "hibob" | "bamboohr" | "any"required
  • include_payboolean

    Pay history (private): only with the pay tier.

    Default false.

  • include_documentsboolean

    People's document files, in a folder per person, with an index.

    Default false.

  • include_leftboolean

    People who left, with their leaving date.

    Default true.

Returns

9 fields
  • tool"personio" | "factorial" | "sesame" | "hibob" | "bamboohr" | "any"required
  • languagestringrequired
  • countsobjectrequired
    12 fields
    • peopleintegerrequired
    • leftintegerrequired
    • historyintegerrequired
    • teamsintegerrequired
    • locationsintegerrequired
    • entitiesintegerrequired
    • fieldsintegerrequired
    • leaveintegerrequired
    • balancesintegerrequired
    • documentsintegerrequired
    • documents_bytesnumberrequired
    • documents_left_outintegerrequired
  • payobjectrequired
    2 fields
    • availablebooleanrequired
    • peopleintegerrequired
  • filesobject[]required
    2 fields
    • namestringrequired
    • whatstringrequired
  • warningsstring[]required

    Values the destination does not know, and what they become.

  • notesstring[]required

    What the destination can't import from a file (e.g. no time-off import): included as a readable CSV anyway.

  • help_urlstring | nullrequired
  • max_bytesintegerrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
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
}'
Response
{
  "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_start on HR Assistant
Preview
?dry_run=true runs 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"required
  • include_payboolean

    Pay history (private): only with the pay tier.

    Default false.

  • include_documentsboolean

    People's document files, in a folder per person, with an index.

    Default false.

  • include_leftboolean

    People who left, with their leaving date.

    Default true.

  • reasonstring

    Up to 1000 characters.

Returns

11 fields
  • idstringrequired
  • tool"personio" | "factorial" | "sesame" | "hibob" | "bamboohr" | "any"required
  • status"building" | "ready" | "failed" | "removed"required
  • optionsobjectrequired
    3 fields
    • paybooleanrequired
    • documentsbooleanrequired
    • leftbooleanrequired
  • countsobjectrequired
    6 fields
    • peopleintegerrequired
    • historyintegerrequired
    • leaveintegerrequired
    • balancesintegerrequired
    • documentsintegerrequired
    • documents_left_outintegerrequired
  • warningsstring[]required
  • fileobject | nullrequired
    2 fields
    • namestringrequired
    • sizeintegerrequired
  • errorstring | nullrequired
  • created_atstringrequired
  • ready_atstring | nullrequired
  • download_untilstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
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."
}'
Response
{
  "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_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • export_idstringrequired

    1–64 characters.

Returns

11 fields
  • idstringrequired
  • tool"personio" | "factorial" | "sesame" | "hibob" | "bamboohr" | "any"required
  • status"building" | "ready" | "failed" | "removed"required
  • optionsobjectrequired
    3 fields
    • paybooleanrequired
    • documentsbooleanrequired
    • leftbooleanrequired
  • countsobjectrequired
    6 fields
    • peopleintegerrequired
    • historyintegerrequired
    • leaveintegerrequired
    • balancesintegerrequired
    • documentsintegerrequired
    • documents_left_outintegerrequired
  • warningsstring[]required
  • fileobject | nullrequired
    2 fields
    • namestringrequired
    • sizeintegerrequired
  • errorstring | nullrequired
  • created_atstringrequired
  • ready_atstring | nullrequired
  • download_untilstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/migration/exports.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"export_id":"ex1"}'
Response
{
  "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_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

An array of objects with 11 fields

An array of objects:

  • idstringrequired
  • tool"personio" | "factorial" | "sesame" | "hibob" | "bamboohr" | "any"required
  • status"building" | "ready" | "failed" | "removed"required
  • optionsobjectrequired
    3 fields
    • paybooleanrequired
    • documentsbooleanrequired
    • leftbooleanrequired
  • countsobjectrequired
    6 fields
    • peopleintegerrequired
    • historyintegerrequired
    • leaveintegerrequired
    • balancesintegerrequired
    • documentsintegerrequired
    • documents_left_outintegerrequired
  • warningsstring[]required
  • fileobject | nullrequired
    2 fields
    • namestringrequired
    • sizeintegerrequired
  • errorstring | nullrequired
  • created_atstringrequired
  • ready_atstring | nullrequired
  • download_untilstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/migration/exports.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "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_download on HR Assistant
Preview
?dry_run=true runs 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_idstringrequired

    1–64 characters.

Returns

  • urlstring | nullrequired

    null on a dry run.

  • expires_atstring | nullrequired
  • file_namestringrequired
  • sizeintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
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"}'
Response
{
  "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_remove on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • export_idstringrequired

    1–64 characters.

Returns

11 fields
  • idstringrequired
  • tool"personio" | "factorial" | "sesame" | "hibob" | "bamboohr" | "any"required
  • status"building" | "ready" | "failed" | "removed"required
  • optionsobjectrequired
    3 fields
    • paybooleanrequired
    • documentsbooleanrequired
    • leftbooleanrequired
  • countsobjectrequired
    6 fields
    • peopleintegerrequired
    • historyintegerrequired
    • leaveintegerrequired
    • balancesintegerrequired
    • documentsintegerrequired
    • documents_left_outintegerrequired
  • warningsstring[]required
  • fileobject | nullrequired
    2 fields
    • namestringrequired
    • sizeintegerrequired
  • errorstring | nullrequired
  • created_atstringrequired
  • ready_atstring | nullrequired
  • download_untilstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
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"}'
Response
{
  "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.

Developer docs