Skip to content

API reference

Change sets

Several changes as one, all or nothing, and drafts a person reviews and applies in Bizisy.

5 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.

Apply a change set#

POST/v1/org/changes.applyDestructive

Applies several changes as one: up to 50 operations, in order, each through its own tool with the same checks and approval rules — hire (org_people_hire), move (org_people_move), promote (org_people_promote), mark_leaving (org_people_mark_leaving), create_team (org_units_create), set_team_lead (org_units_set_head), pay (org_pay_add: in the app only), retitle (org_people_change_job with a new title: { person, effective_date, title }), title_update (org_titles_update: { title: id or { name }, family_id, track, level_id, description } — how to suggest families and levels for the job title catalog). Name people as {id}, {email} or {name}, and teams as {id} or {name}; a team created earlier in the same set can be named by later operations. A name that matches several people stops everything with the candidates. All or nothing: if one operation fails, none is applied, and the error says which (details.change). Use dry_run first: results lists each operation's preview and approvals, and fingerprint identifies the data it was planned on; send expect_fingerprint with the real call to make sure nothing changed in between. draft_id applies a saved draft (org_changes_draft) once; its touches_preparer says when it changes the job or pay of the person who prepared it (tell the user: the changes are recorded as theirs), and such a draft is refused over an API key or MCP: a person applies it in the app. Owners, admins and HR; also a custom role with People and jobs at Edit that covers everyone (no people filters), for ops it sends (never draft_id): each operation still needs that role's area for it (pay: Pay at Edit; teams and job titles: Structure at Edit; team leads: never), and one refused operation stops the set.

Who can call it
Manage key owner admin hr
Keys and apps
Pay changes are refused: save the set with org.changes.draft and a person applies it in the app.
MCP tool
org_changes_apply 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

  • opsobject[]

    1–50 items.

    50 fields (one of several shapes)

    Option 1

    • type"hire"required
    • given_namestringrequired

      1–100 characters.

    • family_namestringrequired

      1–100 characters.

    • work_emailstringrequired

      Up to 200 characters.

    • titlestringrequired

      1–120 characters.

    • start_datestringrequired
    • managerstring | object

      A person id.

      3 fields (one of several shapes)

      Option 1

      • idstringrequired

      Option 2

      • emailstringrequired

        3–200 characters.

      Option 3

      • namestringrequired

        2–200 characters.

    • teamstring | object

      A team id.

      2 fields (one of several shapes)

      Option 1

      • idstringrequired

      Option 2

      • namestringrequired

        1–100 characters.

    • employment_type"full_time" | "part_time" | "contractor" | "intern"

    Option 2

    • type"move"required
    • peoplestring | object[]required

      1–50 items.

      3 fields (one of several shapes)

      Option 1

      • idstringrequired

      Option 2

      • emailstringrequired

        3–200 characters.

      Option 3

      • namestringrequired

        2–200 characters.

    • effective_datestringrequired
    • managerstring | object

      A person id.

      3 fields (one of several shapes)

      Option 1

      • idstringrequired

      Option 2

      • emailstringrequired

        3–200 characters.

      Option 3

      • namestringrequired

        2–200 characters.

    • teamstring | object

      A team id.

      2 fields (one of several shapes)

      Option 1

      • idstringrequired

      Option 2

      • namestringrequired

        1–100 characters.

    Option 3

    • type"promote"required
    • personstring | objectrequired

      A person id.

      3 fields (one of several shapes)

      Option 1

      • idstringrequired

      Option 2

      • emailstringrequired

        3–200 characters.

      Option 3

      • namestringrequired

        2–200 characters.

    • effective_datestringrequired
    • titlestring

      1–120 characters.

    • payobject
      4 fields (one of several shapes)

      Option 1

      • amountnumberrequired

        From 0 to 100000000.

      • currencyanyrequired
      • period"year" | "month" | "hour"required

      Option 2

      • percentnumberrequired

        From -50 to 200.

    Option 4

    • type"mark_leaving"required
    • personstring | objectrequired

      A person id.

      3 fields (one of several shapes)

      Option 1

      • idstringrequired

      Option 2

      • emailstringrequired

        3–200 characters.

      Option 3

      • namestringrequired

        2–200 characters.

    • last_daystringrequired
    • reasonstring

      Up to 200 characters.

    • leaving_typestring (enum)

      One of: resignation, retirement, dismissal, redundancy, end_of_contract, mutual_agreement, death, other.

    • person_toldboolean
    • access"after_last_day" | "keep"

    Option 5

    • type"create_team"required
    • namestringrequired

      1–100 characters.

    • parentstring | object

      A team id.

      2 fields (one of several shapes)

      Option 1

      • idstringrequired

      Option 2

      • namestringrequired

        1–100 characters.

    • kind"division" | "department" | "team"

    Option 6

    • type"set_team_lead"required
    • teamstring | objectrequired

      A team id.

      2 fields (one of several shapes)

      Option 1

      • idstringrequired

      Option 2

      • namestringrequired

        1–100 characters.

    • personstring | objectrequired

      A person id.

      3 fields (one of several shapes)

      Option 1

      • idstringrequired

      Option 2

      • emailstringrequired

        3–200 characters.

      Option 3

      • namestringrequired

        2–200 characters.

    Option 7

    • type"pay"required
    • personstring | objectrequired

      A person id.

      3 fields (one of several shapes)

      Option 1

      • idstringrequired

      Option 2

      • emailstringrequired

        3–200 characters.

      Option 3

      • namestringrequired

        2–200 characters.

    • effective_datestringrequired
    • amountnumberrequired

      From 0 to 100000000.

    • currencyanyrequired
    • period"year" | "month" | "hour"required
    • notestring

      Up to 200 characters.

    Option 8

    • type"retitle"required
    • personstring | objectrequired

      A person id.

      3 fields (one of several shapes)

      Option 1

      • idstringrequired

      Option 2

      • emailstringrequired

        3–200 characters.

      Option 3

      • namestringrequired

        2–200 characters.

    • effective_datestringrequired
    • titlestringrequired

      The new job title as typed (matched to the catalog, else added when applied).

      1–120 characters.

    Option 9

    • type"title_update"required
    • titlestring | objectrequired

      A job title id.

      2 fields (one of several shapes)

      Option 1

      • idstringrequired

      Option 2

      • namestringrequired

        1–120 characters.

    • family_idstring | null
    • track"ic" | "manager"
    • level_idstring | null
    • descriptionstring | null

      Up to 4000 characters.

  • draft_idstring
  • expect_fingerprintstring

    Up to 64 characters.

Returns

  • resultsobject[]required
    6 fields
    • changeintegerrequired
    • typestring (enum)required

      One of: hire, move, promote, mark_leaving, create_team, set_team_lead, pay, retitle, title_update.

    • actionstringrequired
    • created_idstring | nullrequired
    • approvalobject | nullrequired
      11 fields
      • idstringrequired
      • status"pending" | "approved"required
      • waiting_for"manager" | "hr"required
      • approversstring[]required
      • automaticbooleanrequired
      • note"proposed_by_approver" | "no_other_approver"required
      • fallbackbooleanrequired
      • team_leadobject | nullrequired
        3 fields
        • unit_idstringrequired
        • unit_namestringrequired
        • reason"no_manager" | "manager_left"required
      • team_lead_blockedobject | nullrequired
        3 fields
        • unit_idstringrequired
        • unit_namestringrequired
        • what"lead" | "removed" | "moved" | "archived"required
      • untrusted"no_login" | "invited_by_proposer"required
      • then"manager" | "hr"required
    • previewobject | nullrequired
      4 fields
      • summarystringrequired
      • changesobject[]required
        6 fields
        • personobjectrequired
          2 fields
          • idstringrequired
          • namestringrequired
        • fieldstringrequired
        • labelstringrequired
        • fromstring | nullrequired
        • tostring | nullrequired
        • effectivestringrequired
      • approvals_neededobject[]required
        3 fields
        • personobjectrequired
          2 fields
          • idstringrequired
          • namestringrequired
        • waiting_for"manager" | "hr"required
        • approversstring[]required
      • blockedobject[]required
        2 fields
        • personobjectrequired
          2 fields
          • idstringrequired
          • namestringrequired
        • reasonstringrequired
  • fingerprintstringrequired
  • appliedbooleanrequired
  • draft_idstring | nullrequired
  • touches_preparer"job" | "pay"[]required

    A saved draft only: it changes the job or pay of the person who prepared it. Tell the user before applying.

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/changes.apply \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "ops": [
    {
      "type": "create_team",
      "name": "Platform"
    },
    {
      "type": "move",
      "people": [
        {
          "email": "carl@acme.pt"
        }
      ],
      "effective_date": "2026-11-01",
      "team": {
        "name": "Platform"
      },
      "manager": {
        "name": "Ana Costa"
      }
    }
  ],
  "expect_fingerprint": "0123456789abcdef"
}'
Response
{
  "data": {
    "results": [
      {
        "change": 1,
        "type": "create_team",
        "action": "org.units.create",
        "created_id": "u9",
        "approval": null,
        "preview": null
      },
      {
        "change": 2,
        "type": "move",
        "action": "org.people.move",
        "created_id": null,
        "approval": null,
        "preview": {
          "summary": "1 person moves to Platform from 1 Nov 2026.",
          "changes": [],
          "approvals_needed": [],
          "blocked": []
        }
      }
    ],
    "fingerprint": "0123456789abcdef",
    "applied": false,
    "draft_id": null,
    "touches_preparer": []
  }
}

Save a change set for review#

POST/v1/org/changes.draftWrite

Saves a change set (the same ops as org_changes_apply) without applying it, for a person to review and apply in Bizisy — the way to hand over changes you may not apply yourself (pay is applied in the app only) or that the user wants to check first. Every name must already be clear (ambiguous names are refused with the candidates). Returns the draft and its review link (links): show it to the user. Drafts expire after 14 days. Owners, admins and HR.

Who can call it
Manage key owner admin hr
Keys and apps
Pay amounts are never returned.
MCP tool
org_changes_draft 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

  • opsobject[]required

    1–50 items.

    50 fields (one of several shapes)

    Option 1

    • type"hire"required
    • given_namestringrequired

      1–100 characters.

    • family_namestringrequired

      1–100 characters.

    • work_emailstringrequired

      Up to 200 characters.

    • titlestringrequired

      1–120 characters.

    • start_datestringrequired
    • managerstring | object

      A person id.

      3 fields (one of several shapes)

      Option 1

      • idstringrequired

      Option 2

      • emailstringrequired

        3–200 characters.

      Option 3

      • namestringrequired

        2–200 characters.

    • teamstring | object

      A team id.

      2 fields (one of several shapes)

      Option 1

      • idstringrequired

      Option 2

      • namestringrequired

        1–100 characters.

    • employment_type"full_time" | "part_time" | "contractor" | "intern"

    Option 2

    • type"move"required
    • peoplestring | object[]required

      1–50 items.

      3 fields (one of several shapes)

      Option 1

      • idstringrequired

      Option 2

      • emailstringrequired

        3–200 characters.

      Option 3

      • namestringrequired

        2–200 characters.

    • effective_datestringrequired
    • managerstring | object

      A person id.

      3 fields (one of several shapes)

      Option 1

      • idstringrequired

      Option 2

      • emailstringrequired

        3–200 characters.

      Option 3

      • namestringrequired

        2–200 characters.

    • teamstring | object

      A team id.

      2 fields (one of several shapes)

      Option 1

      • idstringrequired

      Option 2

      • namestringrequired

        1–100 characters.

    Option 3

    • type"promote"required
    • personstring | objectrequired

      A person id.

      3 fields (one of several shapes)

      Option 1

      • idstringrequired

      Option 2

      • emailstringrequired

        3–200 characters.

      Option 3

      • namestringrequired

        2–200 characters.

    • effective_datestringrequired
    • titlestring

      1–120 characters.

    • payobject
      4 fields (one of several shapes)

      Option 1

      • amountnumberrequired

        From 0 to 100000000.

      • currencyanyrequired
      • period"year" | "month" | "hour"required

      Option 2

      • percentnumberrequired

        From -50 to 200.

    Option 4

    • type"mark_leaving"required
    • personstring | objectrequired

      A person id.

      3 fields (one of several shapes)

      Option 1

      • idstringrequired

      Option 2

      • emailstringrequired

        3–200 characters.

      Option 3

      • namestringrequired

        2–200 characters.

    • last_daystringrequired
    • reasonstring

      Up to 200 characters.

    • leaving_typestring (enum)

      One of: resignation, retirement, dismissal, redundancy, end_of_contract, mutual_agreement, death, other.

    • person_toldboolean
    • access"after_last_day" | "keep"

    Option 5

    • type"create_team"required
    • namestringrequired

      1–100 characters.

    • parentstring | object

      A team id.

      2 fields (one of several shapes)

      Option 1

      • idstringrequired

      Option 2

      • namestringrequired

        1–100 characters.

    • kind"division" | "department" | "team"

    Option 6

    • type"set_team_lead"required
    • teamstring | objectrequired

      A team id.

      2 fields (one of several shapes)

      Option 1

      • idstringrequired

      Option 2

      • namestringrequired

        1–100 characters.

    • personstring | objectrequired

      A person id.

      3 fields (one of several shapes)

      Option 1

      • idstringrequired

      Option 2

      • emailstringrequired

        3–200 characters.

      Option 3

      • namestringrequired

        2–200 characters.

    Option 7

    • type"pay"required
    • personstring | objectrequired

      A person id.

      3 fields (one of several shapes)

      Option 1

      • idstringrequired

      Option 2

      • emailstringrequired

        3–200 characters.

      Option 3

      • namestringrequired

        2–200 characters.

    • effective_datestringrequired
    • amountnumberrequired

      From 0 to 100000000.

    • currencyanyrequired
    • period"year" | "month" | "hour"required
    • notestring

      Up to 200 characters.

    Option 8

    • type"retitle"required
    • personstring | objectrequired

      A person id.

      3 fields (one of several shapes)

      Option 1

      • idstringrequired

      Option 2

      • emailstringrequired

        3–200 characters.

      Option 3

      • namestringrequired

        2–200 characters.

    • effective_datestringrequired
    • titlestringrequired

      The new job title as typed (matched to the catalog, else added when applied).

      1–120 characters.

    Option 9

    • type"title_update"required
    • titlestring | objectrequired

      A job title id.

      2 fields (one of several shapes)

      Option 1

      • idstringrequired

      Option 2

      • namestringrequired

        1–120 characters.

    • family_idstring | null
    • track"ic" | "manager"
    • level_idstring | null
    • descriptionstring | null

      Up to 4000 characters.

  • notestring

    Up to 500 characters.

Returns

11 fields
  • idstringrequired
  • status"pending" | "applied" | "discarded" | "expired"required
  • notestring | nullrequired
  • opsany[]required

    The changes, as sent (pay amounts only for those who may see pay).

  • summarystringrequired
  • linesstring[]required

    Each change in words, in order, with names (pay amounts only for those who may see pay).

  • prepared_byobjectrequired
    3 fields
    • user_idstringrequired
    • namestring | nullrequired
    • machinebooleanrequired
  • touches_preparer"job" | "pay"[]required

    Whether the set changes the job or the pay of the person who prepared it (directly or through an AI app they connected). Applying it records the changes as the applier's, so the rules about one's own records check the applier: check these changes with particular care.

  • created_atstringrequired
  • expires_onstringrequired
  • closed_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/changes.draft \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "ops": [
    {
      "type": "pay",
      "person": "p1",
      "effective_date": "2026-11-01",
      "amount": 3200,
      "currency": "EUR",
      "period": "month"
    }
  ],
  "note": "Annual review"
}'
Response
{
  "data": {
    "id": "d1",
    "status": "pending",
    "note": "Annual review",
    "ops": [
      {
        "type": "pay",
        "person": "p1",
        "effective_date": "2026-11-01",
        "amount": 3200,
        "currency": "EUR",
        "period": "month"
      }
    ],
    "summary": "pay",
    "lines": [
      "Pay Ana Ferreira 3200 EUR a month from 1 Nov 2026"
    ],
    "prepared_by": {
      "user_id": "u1",
      "name": "Ana Ferreira",
      "machine": true
    },
    "touches_preparer": [
      "pay"
    ],
    "created_at": "2026-10-07T10:00:00.000Z",
    "expires_on": "2026-10-21",
    "closed_at": null
  }
}

List change sets to review#

POST/v1/org/changes.listRead

Change sets saved for review (org_changes_draft): pending ones first, then those applied, discarded or expired in the last 30 days. Pay amounts only for owners, admins and HR in the app. Owners, admins and HR.

Who can call it
Manage key owner admin hr
Keys and apps
Pay amounts are never returned.
MCP tool
org_changes_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • draftsobject[]required
    11 fields
    • idstringrequired
    • status"pending" | "applied" | "discarded" | "expired"required
    • notestring | nullrequired
    • opsany[]required

      The changes, as sent (pay amounts only for those who may see pay).

    • summarystringrequired
    • linesstring[]required

      Each change in words, in order, with names (pay amounts only for those who may see pay).

    • prepared_byobjectrequired
      3 fields
      • user_idstringrequired
      • namestring | nullrequired
      • machinebooleanrequired
    • touches_preparer"job" | "pay"[]required

      Whether the set changes the job or the pay of the person who prepared it (directly or through an AI app they connected). Applying it records the changes as the applier's, so the rules about one's own records check the applier: check these changes with particular care.

    • created_atstringrequired
    • expires_onstringrequired
    • closed_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/changes.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "drafts": [
      {
        "id": "d1",
        "status": "pending",
        "note": "Annual review",
        "ops": [
          {
            "type": "pay",
            "person": "p1",
            "effective_date": "2026-11-01",
            "amount": 3200,
            "currency": "EUR",
            "period": "month"
          }
        ],
        "summary": "pay",
        "lines": [
          "Pay Ana Ferreira 3200 EUR a month from 1 Nov 2026"
        ],
        "prepared_by": {
          "user_id": "u1",
          "name": "Ana Ferreira",
          "machine": true
        },
        "touches_preparer": [
          "pay"
        ],
        "created_at": "2026-10-07T10:00:00.000Z",
        "expires_on": "2026-10-21",
        "closed_at": null
      }
    ]
  }
}

Get a change set draft#

POST/v1/org/changes.getRead

One change set draft: its changes, status (pending, applied, discarded or expired) and who prepared it. Preview it with org_changes_apply (draft_id, dry_run). Pay amounts only for owners, admins and HR in the app. Owners, admins and HR.

Who can call it
Manage key owner admin hr
Keys and apps
Pay amounts are never returned.
MCP tool
org_changes_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • draft_idstringrequired

Returns

11 fields
  • idstringrequired
  • status"pending" | "applied" | "discarded" | "expired"required
  • notestring | nullrequired
  • opsany[]required

    The changes, as sent (pay amounts only for those who may see pay).

  • summarystringrequired
  • linesstring[]required

    Each change in words, in order, with names (pay amounts only for those who may see pay).

  • prepared_byobjectrequired
    3 fields
    • user_idstringrequired
    • namestring | nullrequired
    • machinebooleanrequired
  • touches_preparer"job" | "pay"[]required

    Whether the set changes the job or the pay of the person who prepared it (directly or through an AI app they connected). Applying it records the changes as the applier's, so the rules about one's own records check the applier: check these changes with particular care.

  • created_atstringrequired
  • expires_onstringrequired
  • closed_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/changes.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"draft_id":"d1"}'
Response
{
  "data": {
    "id": "d1",
    "status": "pending",
    "note": "Annual review",
    "ops": [
      {
        "type": "pay",
        "person": "p1",
        "effective_date": "2026-11-01",
        "amount": 3200,
        "currency": "EUR",
        "period": "month"
      }
    ],
    "summary": "pay",
    "lines": [
      "Pay Ana Ferreira 3200 EUR a month from 1 Nov 2026"
    ],
    "prepared_by": {
      "user_id": "u1",
      "name": "Ana Ferreira",
      "machine": true
    },
    "touches_preparer": [
      "pay"
    ],
    "created_at": "2026-10-07T10:00:00.000Z",
    "expires_on": "2026-10-21",
    "closed_at": null
  }
}

Discard a change set draft#

POST/v1/org/changes.discardWrite

Discards a pending draft: nothing in it is applied. Owners, admins and HR.

Who can call it
Manage key owner admin hr
MCP tool
org_changes_discard on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • draft_idstringrequired

Returns

11 fields
  • idstringrequired
  • status"pending" | "applied" | "discarded" | "expired"required
  • notestring | nullrequired
  • opsany[]required

    The changes, as sent (pay amounts only for those who may see pay).

  • summarystringrequired
  • linesstring[]required

    Each change in words, in order, with names (pay amounts only for those who may see pay).

  • prepared_byobjectrequired
    3 fields
    • user_idstringrequired
    • namestring | nullrequired
    • machinebooleanrequired
  • touches_preparer"job" | "pay"[]required

    Whether the set changes the job or the pay of the person who prepared it (directly or through an AI app they connected). Applying it records the changes as the applier's, so the rules about one's own records check the applier: check these changes with particular care.

  • created_atstringrequired
  • expires_onstringrequired
  • closed_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/changes.discard \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"draft_id":"d1"}'
Response
{
  "data": {
    "id": "d1",
    "status": "discarded",
    "note": "Annual review",
    "ops": [
      {
        "type": "pay",
        "person": "p1",
        "effective_date": "2026-11-01",
        "amount": 3200,
        "currency": "EUR",
        "period": "month"
      }
    ],
    "summary": "pay",
    "lines": [
      "Pay Ana Ferreira 3200 EUR a month from 1 Nov 2026"
    ],
    "prepared_by": {
      "user_id": "u1",
      "name": "Ana Ferreira",
      "machine": true
    },
    "touches_preparer": [
      "pay"
    ],
    "created_at": "2026-10-07T10:00:00.000Z",
    "expires_on": "2026-10-21",
    "closed_at": "2026-10-08T09:00:00.000Z"
  }
}

Something missing or wrong on this page? Write to hello@bizisy.com.

Developer docs