Skip to content

API reference

Open positions

Roles the company plans to fill and headcount budgets per team: the headcount plan.

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

List open positions (headcount plan)#

POST/v1/org/positions.listRead

Lists open positions: roles the company plans to fill (title, team, location, legal entity, who it reports to — a person or another position —, contract type, weekly hours, target start date, status, reason "new" or "replacement" with the leaver it replaces, and who filled it). status: "active" (default: draft, open and on hold), one status (draft, open, on_hold, filled, cancelled), "closed" (filled and cancelled) or "all". Filled and cancelled positions come newest first, a page at a time: limit (default 50, at most 200) of them per call; for the next page pass after = the id of the last closed position you got (only with filled, cancelled, closed or all; with all the draft, open and on-hold ones come only on the first page). Filters: unit_id, reports_to_person_id. Who sees what: owners, admins and HR see every position; a manager sees only the open and on-hold positions that report to them or to someone below them (also when that person starts later or has left: the line they belong to); everyone else sees none (an empty list). notes are for owners, admins and HR only; pay_range (the budget) only for owners, admins and HR signed in to Bizisy, never over MCP or an API key (pay_range_hidden is then true); replaces is shown only when you may see that person's job details. can_reopen: a filled position whose hire did not start (org_positions_reopen).

Who can call it
Manage key any Manage role
Me key anyone
Keys and apps
pay_range (the budget) is never returned (pay_range_hidden is true).
MCP tool
org_positions_list on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • statusstring (enum)

    One of: active, draft, open, on_hold, filled, cancelled, closed, all. Default "active".

  • unit_idstring
  • reports_to_person_idstring
  • limitinteger

    From 1 to 200.

  • afterstring

Returns

An array of objects with 26 fields

An array of objects:

  • idstringrequired
  • titlestringrequired
  • title_idstring | nullrequired
  • status"draft" | "open" | "on_hold" | "filled" | "cancelled"required
  • reason"new" | "replacement"required
  • unitobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • locationobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • legal_entityobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • reports_to_personobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • reports_to_positionobject | nullrequired
    2 fields
    • idstringrequired
    • titlestringrequired
  • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
  • weekly_hoursnumber | nullrequired
  • pay_rangeobject | nullrequired
    4 fields
    • minnumberrequired
    • maxnumberrequired
    • currencystringrequired
    • period"year" | "month" | "hour"required
  • pay_range_hiddenbooleanrequired
  • target_start_datestring | nullrequired
  • notesstring | nullrequired
  • replacesobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • filled_byobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • filled_onstring | nullrequired
  • can_reopenbooleanrequired
  • requestobject | nullrequired
    4 fields
    • byobject | nullrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • atstringrequired
    • notestring | nullrequired
    • withdrawnbooleanrequired
  • title_descriptionstring | nullrequired
  • customobject[]required
    7 fields
    • keystringrequired
    • labelstringrequired
    • typestring (enum)required

      One of: text, number, date, select, boolean, file, person, table.

    • tier"public" | "job" | "private"required
    • valuestring | number | boolean | object[]required

      For type file: the document id (download it with documents_download or documents_me_download); over an API key or MCP, "attached" for someone else's file. For type person: the person id. For type table: the rows, [{ <column key>: value }] (columns in org_fields_list).

    • fileobject | null

      Type file only: the file, or null when none is attached.

      4 fields
      • namestring | nullrequired

        The file name; null over an API key or MCP for someone else's file.

      • sizeintegerrequired
      • content_typestringrequired
      • previewablebooleanrequired

        The web app can show it (PDF, PNG, JPEG, WebP).

    • personobject | null

      Type person only: who it names (null when not set, or not someone you may see).

      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
  • approvalobject | nullrequired
    7 fields
    • state"pending" | "approved" | "rejected" | "withdrawn"required
    • reasons"always" | "over_plan" | "above_band"[]required

      Why it needed approval: always, new headcount over the plan, pay above the band.

    • target_status"open" | "on_hold"required
    • asked_byobject | nullrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • asked_atstringrequired
    • stepsobject[]required
      8 fields
      • kind"manager" | "hr" | "role" | "person"required
      • labelstringrequired

        Who decides it: the manager, HR, a role or a person.

      • state"waiting" | "pending" | "approved" | "rejected"required
      • byobject | nullrequired
        4 fields
        • idstringrequired
        • namestringrequired
        • titlestring | nullrequired
        • photo_urlstring | nullrequired
      • atstring | nullrequired
      • commentstring | nullrequired
      • autobooleanrequired

        Approved by itself: nobody but the proposer could decide it (noted).

      • fallbackbooleanrequired

        HR decides in place of the step's own approver, who could not.

    • closed_atstring | nullrequired
  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/positions.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"on_hold","unit_id":"u1","reports_to_person_id":"p1"}'
Response
{
  "data": [
    {
      "id": "pos1",
      "title": "Data Engineer",
      "title_id": "t2",
      "status": "open",
      "reason": "replacement",
      "unit": {
        "id": "u2",
        "name": "Engineering"
      },
      "location": {
        "id": "l1",
        "name": "Lisbon"
      },
      "legal_entity": {
        "id": "e1",
        "name": "Acme Lda"
      },
      "reports_to_person": {
        "id": "p1",
        "name": "Ana Ferreira",
        "title": "CTO",
        "photo_url": null
      },
      "reports_to_position": null,
      "contract_type": "permanent",
      "weekly_hours": 40,
      "pay_range": null,
      "pay_range_hidden": true,
      "target_start_date": "2026-12-01",
      "notes": "Budget approved in Q3",
      "replaces": {
        "id": "p3",
        "name": "Rui Costa",
        "title": "Data Engineer",
        "photo_url": null
      },
      "filled_by": null,
      "filled_on": null,
      "can_reopen": false,
      "request": {
        "by": {
          "id": "p2",
          "name": "Tomás Silva",
          "title": "Engineering Manager",
          "photo_url": null
        },
        "at": "2026-10-03T09:00:00.000Z",
        "note": "Rui leaves at the end of November.",
        "withdrawn": false
      },
      "title_description": "Builds and runs the data pipelines the company reports from.",
      "custom": [
        {
          "key": "hiring_manager",
          "label": "Hiring manager",
          "type": "person",
          "tier": "public",
          "value": "p1",
          "person": {
            "id": "p1",
            "name": "Ana Ferreira",
            "title": "CTO",
            "photo_url": null
          }
        }
      ],
      "approval": null,
      "created_at": "2026-10-04T10:00:00.000Z",
      "updated_at": "2026-10-04T10:00:00.000Z"
    },
    {
      "id": "pos2",
      "title": "Data Engineer",
      "title_id": "t2",
      "status": "on_hold",
      "reason": "new",
      "unit": {
        "id": "u2",
        "name": "Engineering"
      },
      "location": {
        "id": "l1",
        "name": "Lisbon"
      },
      "legal_entity": {
        "id": "e1",
        "name": "Acme Lda"
      },
      "reports_to_person": null,
      "reports_to_position": {
        "id": "pos1",
        "title": "Data Engineer"
      },
      "contract_type": "permanent",
      "weekly_hours": 40,
      "pay_range": null,
      "pay_range_hidden": true,
      "target_start_date": "2026-12-01",
      "notes": null,
      "replaces": null,
      "filled_by": null,
      "filled_on": null,
      "can_reopen": false,
      "request": {
        "by": {
          "id": "p2",
          "name": "Tomás Silva",
          "title": "Engineering Manager",
          "photo_url": null
        },
        "at": "2026-10-03T09:00:00.000Z",
        "note": "Rui leaves at the end of November.",
        "withdrawn": false
      },
      "title_description": "Builds and runs the data pipelines the company reports from.",
      "custom": [
        {
          "key": "hiring_manager",
          "label": "Hiring manager",
          "type": "person",
          "tier": "public",
          "value": "p1",
          "person": {
            "id": "p1",
            "name": "Ana Ferreira",
            "title": "CTO",
            "photo_url": null
          }
        }
      ],
      "approval": null,
      "created_at": "2026-10-04T10:00:00.000Z",
      "updated_at": "2026-10-04T10:00:00.000Z"
    }
  ]
}

Get an open position#

POST/v1/org/positions.getRead

Returns one position with the same visibility as org_positions_list: owners, admins and HR any position (filled and cancelled ones too); a manager the open and on-hold positions in their line; otherwise not_found.

Who can call it
Manage key any Manage role
Me key anyone
MCP tool
org_positions_get on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • position_idstringrequired

Returns

26 fields
  • idstringrequired
  • titlestringrequired
  • title_idstring | nullrequired
  • status"draft" | "open" | "on_hold" | "filled" | "cancelled"required
  • reason"new" | "replacement"required
  • unitobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • locationobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • legal_entityobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • reports_to_personobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • reports_to_positionobject | nullrequired
    2 fields
    • idstringrequired
    • titlestringrequired
  • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
  • weekly_hoursnumber | nullrequired
  • pay_rangeobject | nullrequired
    4 fields
    • minnumberrequired
    • maxnumberrequired
    • currencystringrequired
    • period"year" | "month" | "hour"required
  • pay_range_hiddenbooleanrequired
  • target_start_datestring | nullrequired
  • notesstring | nullrequired
  • replacesobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • filled_byobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • filled_onstring | nullrequired
  • can_reopenbooleanrequired
  • requestobject | nullrequired
    4 fields
    • byobject | nullrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • atstringrequired
    • notestring | nullrequired
    • withdrawnbooleanrequired
  • title_descriptionstring | nullrequired
  • customobject[]required
    7 fields
    • keystringrequired
    • labelstringrequired
    • typestring (enum)required

      One of: text, number, date, select, boolean, file, person, table.

    • tier"public" | "job" | "private"required
    • valuestring | number | boolean | object[]required

      For type file: the document id (download it with documents_download or documents_me_download); over an API key or MCP, "attached" for someone else's file. For type person: the person id. For type table: the rows, [{ <column key>: value }] (columns in org_fields_list).

    • fileobject | null

      Type file only: the file, or null when none is attached.

      4 fields
      • namestring | nullrequired

        The file name; null over an API key or MCP for someone else's file.

      • sizeintegerrequired
      • content_typestringrequired
      • previewablebooleanrequired

        The web app can show it (PDF, PNG, JPEG, WebP).

    • personobject | null

      Type person only: who it names (null when not set, or not someone you may see).

      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
  • approvalobject | nullrequired
    7 fields
    • state"pending" | "approved" | "rejected" | "withdrawn"required
    • reasons"always" | "over_plan" | "above_band"[]required

      Why it needed approval: always, new headcount over the plan, pay above the band.

    • target_status"open" | "on_hold"required
    • asked_byobject | nullrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • asked_atstringrequired
    • stepsobject[]required
      8 fields
      • kind"manager" | "hr" | "role" | "person"required
      • labelstringrequired

        Who decides it: the manager, HR, a role or a person.

      • state"waiting" | "pending" | "approved" | "rejected"required
      • byobject | nullrequired
        4 fields
        • idstringrequired
        • namestringrequired
        • titlestring | nullrequired
        • photo_urlstring | nullrequired
      • atstring | nullrequired
      • commentstring | nullrequired
      • autobooleanrequired

        Approved by itself: nobody but the proposer could decide it (noted).

      • fallbackbooleanrequired

        HR decides in place of the step's own approver, who could not.

    • closed_atstring | nullrequired
  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/positions.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"position_id":"pos1"}'
Response
{
  "data": {
    "id": "pos1",
    "title": "Data Engineer",
    "title_id": "t2",
    "status": "open",
    "reason": "replacement",
    "unit": {
      "id": "u2",
      "name": "Engineering"
    },
    "location": {
      "id": "l1",
      "name": "Lisbon"
    },
    "legal_entity": {
      "id": "e1",
      "name": "Acme Lda"
    },
    "reports_to_person": {
      "id": "p1",
      "name": "Ana Ferreira",
      "title": "CTO",
      "photo_url": null
    },
    "reports_to_position": null,
    "contract_type": "permanent",
    "weekly_hours": 40,
    "pay_range": null,
    "pay_range_hidden": true,
    "target_start_date": "2026-12-01",
    "notes": "Budget approved in Q3",
    "replaces": {
      "id": "p3",
      "name": "Rui Costa",
      "title": "Data Engineer",
      "photo_url": null
    },
    "filled_by": null,
    "filled_on": null,
    "can_reopen": false,
    "request": {
      "by": {
        "id": "p2",
        "name": "Tomás Silva",
        "title": "Engineering Manager",
        "photo_url": null
      },
      "at": "2026-10-03T09:00:00.000Z",
      "note": "Rui leaves at the end of November.",
      "withdrawn": false
    },
    "title_description": "Builds and runs the data pipelines the company reports from.",
    "custom": [
      {
        "key": "hiring_manager",
        "label": "Hiring manager",
        "type": "person",
        "tier": "public",
        "value": "p1",
        "person": {
          "id": "p1",
          "name": "Ana Ferreira",
          "title": "CTO",
          "photo_url": null
        }
      }
    ],
    "approval": null,
    "created_at": "2026-10-04T10:00:00.000Z",
    "updated_at": "2026-10-04T10:00:00.000Z"
  }
}

Create an open position#

POST/v1/org/positions.createWrite

Plans a role to fill. Required: title. Optional: status (open by default, or draft or on_hold), unit_id, location_id and legal_entity_id (default to the only active one), reports_to_person_id (someone employed now or starting soon) or reports_to_position_id (another draft, open or on-hold position; never both), contract_type, weekly_hours, target_start_date (YYYY-MM-DD), notes (owners, admins and HR only; do not put personal data here), reason ("new", default, or "replacement" with an optional replaces_person_id: the leaver), pay_range {min, max, currency, period: year, month or hour} — the budget, which can only be set by signing in to Bizisy (refused over MCP or an API key) —, and custom (position custom fields, org_fields_list target position, e.g. a cost centre; private ones are refused over MCP or an API key). At most 500 draft, open or on-hold positions per organization. Owners, admins and HR. Use dry_run first. To fill it, hire someone with org_people_hire and position_id.

Who can call it
Manage key owner admin hr
Keys and apps
pay_range and private custom fields are refused.
MCP tool
org_positions_create 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

  • titlestring

    The job title as typed: matched to the job title catalog (exact name, an earlier wording, or the same words), else added to it when the change applies (see org_titles_list).

    1–120 characters.

  • title_idstring

    A job title from org_titles_list, instead of title.

  • create_titleboolean

    false: refuse a title that is not in the catalog yet (not_found with details.candidates) instead of adding it.

  • status"draft" | "open" | "on_hold"
  • unit_idstring | null
  • location_idstring | null
  • legal_entity_idstring | null
  • reports_to_person_idstring | null
  • reports_to_position_idstring | null
  • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"
  • weekly_hoursnumber | null

    From 0 to 80.

  • pay_rangeobject | null
    4 fields
    • minnumberrequired

      From 0 to 100000000.

    • maxnumberrequired

      From 0 to 100000000.

    • currencyanyrequired
    • period"year" | "month" | "hour"required
  • target_start_datestring | null
  • notesstring | null

    Up to 1000 characters.

  • reason"new" | "replacement"
  • replaces_person_idstring | null
  • customobject

    Position custom fields (org_fields_list, target position) by key; null clears one. Private ones only in Bizisy, never over an API key or MCP.

Returns

27 fields
  • idstringrequired
  • titlestringrequired
  • title_idstring | nullrequired
  • status"draft" | "open" | "on_hold" | "filled" | "cancelled"required
  • reason"new" | "replacement"required
  • unitobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • locationobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • legal_entityobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • reports_to_personobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • reports_to_positionobject | nullrequired
    2 fields
    • idstringrequired
    • titlestringrequired
  • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
  • weekly_hoursnumber | nullrequired
  • pay_rangeobject | nullrequired
    4 fields
    • minnumberrequired
    • maxnumberrequired
    • currencystringrequired
    • period"year" | "month" | "hour"required
  • pay_range_hiddenbooleanrequired
  • target_start_datestring | nullrequired
  • notesstring | nullrequired
  • replacesobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • filled_byobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • filled_onstring | nullrequired
  • can_reopenbooleanrequired
  • requestobject | nullrequired
    4 fields
    • byobject | nullrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • atstringrequired
    • notestring | nullrequired
    • withdrawnbooleanrequired
  • title_descriptionstring | nullrequired
  • customobject[]required
    7 fields
    • keystringrequired
    • labelstringrequired
    • typestring (enum)required

      One of: text, number, date, select, boolean, file, person, table.

    • tier"public" | "job" | "private"required
    • valuestring | number | boolean | object[]required

      For type file: the document id (download it with documents_download or documents_me_download); over an API key or MCP, "attached" for someone else's file. For type person: the person id. For type table: the rows, [{ <column key>: value }] (columns in org_fields_list).

    • fileobject | null

      Type file only: the file, or null when none is attached.

      4 fields
      • namestring | nullrequired

        The file name; null over an API key or MCP for someone else's file.

      • sizeintegerrequired
      • content_typestringrequired
      • previewablebooleanrequired

        The web app can show it (PDF, PNG, JPEG, WebP).

    • personobject | null

      Type person only: who it names (null when not set, or not someone you may see).

      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
  • approvalobject | nullrequired
    7 fields
    • state"pending" | "approved" | "rejected" | "withdrawn"required
    • reasons"always" | "over_plan" | "above_band"[]required

      Why it needed approval: always, new headcount over the plan, pay above the band.

    • target_status"open" | "on_hold"required
    • asked_byobject | nullrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • asked_atstringrequired
    • stepsobject[]required
      8 fields
      • kind"manager" | "hr" | "role" | "person"required
      • labelstringrequired

        Who decides it: the manager, HR, a role or a person.

      • state"waiting" | "pending" | "approved" | "rejected"required
      • byobject | nullrequired
        4 fields
        • idstringrequired
        • namestringrequired
        • titlestring | nullrequired
        • photo_urlstring | nullrequired
      • atstring | nullrequired
      • commentstring | nullrequired
      • autobooleanrequired

        Approved by itself: nobody but the proposer could decide it (noted).

      • fallbackbooleanrequired

        HR decides in place of the step's own approver, who could not.

    • closed_atstring | nullrequired
  • created_atstringrequired
  • updated_atstringrequired
  • title_matchobject | nullrequired

    What happened to the job title: matched to the catalog, or new to it.

    5 fields
    • idstring | nullrequired

      The catalog title; null while it waits for approval (it is added when the change applies).

    • namestringrequired
    • createdbooleanrequired

      True: the title is new to the catalog (added now, or when an approval applies).

    • matched_fromstring

      What was typed, when the catalog names it differently.

    • similarobject[]

      Catalog titles that look the same as a new one: tell the user before applying.

      3 fields
      • idstringrequired
      • namestringrequired
      • peopleinteger | nullrequired

        Who holds it today; null when you do not see the catalog counts.

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/positions.create \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "title": "Data Engineer",
  "status": "draft",
  "unit_id": "u2",
  "location_id": null,
  "legal_entity_id": "e1",
  "reports_to_person_id": "p1",
  "contract_type": "permanent",
  "weekly_hours": 40,
  "target_start_date": "2026-12-01",
  "notes": "n",
  "reason": "replacement",
  "replaces_person_id": "p3"
}'
Response
{
  "data": {
    "id": "pos1",
    "title": "Data Engineer",
    "title_id": "t2",
    "status": "draft",
    "reason": "replacement",
    "unit": {
      "id": "u2",
      "name": "Engineering"
    },
    "location": {
      "id": "l1",
      "name": "Lisbon"
    },
    "legal_entity": {
      "id": "e1",
      "name": "Acme Lda"
    },
    "reports_to_person": {
      "id": "p1",
      "name": "Ana Ferreira",
      "title": "CTO",
      "photo_url": null
    },
    "reports_to_position": null,
    "contract_type": "permanent",
    "weekly_hours": 40,
    "pay_range": null,
    "pay_range_hidden": true,
    "target_start_date": "2026-12-01",
    "notes": "n",
    "replaces": {
      "id": "p3",
      "name": "Rui Costa",
      "title": "Data Engineer",
      "photo_url": null
    },
    "filled_by": null,
    "filled_on": null,
    "can_reopen": false,
    "request": {
      "by": {
        "id": "p2",
        "name": "Tomás Silva",
        "title": "Engineering Manager",
        "photo_url": null
      },
      "at": "2026-10-03T09:00:00.000Z",
      "note": "Rui leaves at the end of November.",
      "withdrawn": false
    },
    "title_description": "Builds and runs the data pipelines the company reports from.",
    "custom": [
      {
        "key": "hiring_manager",
        "label": "Hiring manager",
        "type": "person",
        "tier": "public",
        "value": "p1",
        "person": {
          "id": "p1",
          "name": "Ana Ferreira",
          "title": "CTO",
          "photo_url": null
        }
      }
    ],
    "approval": null,
    "created_at": "2026-10-04T10:00:00.000Z",
    "updated_at": "2026-10-04T10:00:00.000Z",
    "title_match": {
      "id": "t2",
      "name": "Data Engineer",
      "created": false
    }
  }
}

Change an open position#

POST/v1/org/positions.updateWrite

Changes a position: any field of org_positions_create (null clears one; setting reports_to_person_id clears reports_to_position_id and the other way round; reason "new" clears replaces_person_id) and status: draft → open, on_hold or cancelled; open ↔ on_hold; open or on hold → cancelled; cancelled → draft or open (reopen; who it reports to is checked again). Cancelling a position moves the positions that reported to it to whoever it reported to. "filled" is never set here: hire into the position with org_people_hire and position_id. custom changes position custom fields (org_fields_list, target position; null clears one; private ones are refused over MCP or an API key). A filled position only takes notes and custom fields; if its hire did not start, reopen it with org_positions_reopen. pay_range can only be changed by signing in to Bizisy (refused over MCP or an API key; leave it out to keep it). Owners, admins and HR.

Who can call it
Manage key owner admin hr
Keys and apps
pay_range and private custom fields are refused.
MCP tool
org_positions_update 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

  • position_idstringrequired
  • titlestring

    The job title as typed: matched to the job title catalog (exact name, an earlier wording, or the same words), else added to it when the change applies (see org_titles_list).

    1–120 characters.

  • title_idstring

    A job title from org_titles_list, instead of title.

  • create_titleboolean

    false: refuse a title that is not in the catalog yet (not_found with details.candidates) instead of adding it.

  • status"draft" | "open" | "on_hold" | "filled" | "cancelled"
  • unit_idstring | null
  • location_idstring | null
  • legal_entity_idstring | null
  • reports_to_person_idstring | null
  • reports_to_position_idstring | null
  • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"
  • weekly_hoursnumber | null

    From 0 to 80.

  • pay_rangeobject | null
    4 fields
    • minnumberrequired

      From 0 to 100000000.

    • maxnumberrequired

      From 0 to 100000000.

    • currencyanyrequired
    • period"year" | "month" | "hour"required
  • target_start_datestring | null
  • notesstring | null

    Up to 1000 characters.

  • reason"new" | "replacement"
  • replaces_person_idstring | null
  • customobject

    Position custom fields (org_fields_list, target position) by key; null clears one. Private ones only in Bizisy, never over an API key or MCP.

Returns

26 fields
  • idstringrequired
  • titlestringrequired
  • title_idstring | nullrequired
  • status"draft" | "open" | "on_hold" | "filled" | "cancelled"required
  • reason"new" | "replacement"required
  • unitobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • locationobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • legal_entityobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • reports_to_personobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • reports_to_positionobject | nullrequired
    2 fields
    • idstringrequired
    • titlestringrequired
  • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
  • weekly_hoursnumber | nullrequired
  • pay_rangeobject | nullrequired
    4 fields
    • minnumberrequired
    • maxnumberrequired
    • currencystringrequired
    • period"year" | "month" | "hour"required
  • pay_range_hiddenbooleanrequired
  • target_start_datestring | nullrequired
  • notesstring | nullrequired
  • replacesobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • filled_byobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • filled_onstring | nullrequired
  • can_reopenbooleanrequired
  • requestobject | nullrequired
    4 fields
    • byobject | nullrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • atstringrequired
    • notestring | nullrequired
    • withdrawnbooleanrequired
  • title_descriptionstring | nullrequired
  • customobject[]required
    7 fields
    • keystringrequired
    • labelstringrequired
    • typestring (enum)required

      One of: text, number, date, select, boolean, file, person, table.

    • tier"public" | "job" | "private"required
    • valuestring | number | boolean | object[]required

      For type file: the document id (download it with documents_download or documents_me_download); over an API key or MCP, "attached" for someone else's file. For type person: the person id. For type table: the rows, [{ <column key>: value }] (columns in org_fields_list).

    • fileobject | null

      Type file only: the file, or null when none is attached.

      4 fields
      • namestring | nullrequired

        The file name; null over an API key or MCP for someone else's file.

      • sizeintegerrequired
      • content_typestringrequired
      • previewablebooleanrequired

        The web app can show it (PDF, PNG, JPEG, WebP).

    • personobject | null

      Type person only: who it names (null when not set, or not someone you may see).

      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
  • approvalobject | nullrequired
    7 fields
    • state"pending" | "approved" | "rejected" | "withdrawn"required
    • reasons"always" | "over_plan" | "above_band"[]required

      Why it needed approval: always, new headcount over the plan, pay above the band.

    • target_status"open" | "on_hold"required
    • asked_byobject | nullrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • asked_atstringrequired
    • stepsobject[]required
      8 fields
      • kind"manager" | "hr" | "role" | "person"required
      • labelstringrequired

        Who decides it: the manager, HR, a role or a person.

      • state"waiting" | "pending" | "approved" | "rejected"required
      • byobject | nullrequired
        4 fields
        • idstringrequired
        • namestringrequired
        • titlestring | nullrequired
        • photo_urlstring | nullrequired
      • atstring | nullrequired
      • commentstring | nullrequired
      • autobooleanrequired

        Approved by itself: nobody but the proposer could decide it (noted).

      • fallbackbooleanrequired

        HR decides in place of the step's own approver, who could not.

    • closed_atstring | nullrequired
  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/positions.update \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "position_id": "pos1",
  "title": "Lead",
  "reports_to_position_id": "pos2",
  "reports_to_person_id": null,
  "notes": null,
  "reason": "new"
}'
Response
{
  "data": {
    "id": "pos1",
    "title": "Lead",
    "title_id": "t2",
    "status": "filled",
    "reason": "new",
    "unit": {
      "id": "u2",
      "name": "Engineering"
    },
    "location": {
      "id": "l1",
      "name": "Lisbon"
    },
    "legal_entity": {
      "id": "e1",
      "name": "Acme Lda"
    },
    "reports_to_person": {
      "id": "p1",
      "name": "Ana Ferreira",
      "title": "CTO",
      "photo_url": null
    },
    "reports_to_position": null,
    "contract_type": "permanent",
    "weekly_hours": 40,
    "pay_range": null,
    "pay_range_hidden": true,
    "target_start_date": "2026-12-01",
    "notes": null,
    "replaces": {
      "id": "p3",
      "name": "Rui Costa",
      "title": "Data Engineer",
      "photo_url": null
    },
    "filled_by": {
      "id": "p9",
      "name": "Zoe Lima",
      "title": "Data Engineer",
      "photo_url": null
    },
    "filled_on": "2026-12-01",
    "can_reopen": true,
    "request": {
      "by": {
        "id": "p2",
        "name": "Tomás Silva",
        "title": "Engineering Manager",
        "photo_url": null
      },
      "at": "2026-10-03T09:00:00.000Z",
      "note": "Rui leaves at the end of November.",
      "withdrawn": false
    },
    "title_description": "Builds and runs the data pipelines the company reports from.",
    "custom": [
      {
        "key": "hiring_manager",
        "label": "Hiring manager",
        "type": "person",
        "tier": "public",
        "value": "p1",
        "person": {
          "id": "p1",
          "name": "Ana Ferreira",
          "title": "CTO",
          "photo_url": null
        }
      }
    ],
    "approval": null,
    "created_at": "2026-10-04T10:00:00.000Z",
    "updated_at": "2026-10-04T10:00:00.000Z"
  }
}

Reopen a filled position (the hire did not start)#

POST/v1/org/positions.reopenWrite

Puts a filled position back to open when its hire fell through: the person was terminated on or before their start date, or erased (can_reopen in org_positions_get). The positions that were moved under that person go back under this position, and their job no longer records it. Refused otherwise (conflict). Owners, admins and HR.

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

Input

  • position_idstringrequired

Returns

26 fields
  • idstringrequired
  • titlestringrequired
  • title_idstring | nullrequired
  • status"draft" | "open" | "on_hold" | "filled" | "cancelled"required
  • reason"new" | "replacement"required
  • unitobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • locationobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • legal_entityobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • reports_to_personobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • reports_to_positionobject | nullrequired
    2 fields
    • idstringrequired
    • titlestringrequired
  • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
  • weekly_hoursnumber | nullrequired
  • pay_rangeobject | nullrequired
    4 fields
    • minnumberrequired
    • maxnumberrequired
    • currencystringrequired
    • period"year" | "month" | "hour"required
  • pay_range_hiddenbooleanrequired
  • target_start_datestring | nullrequired
  • notesstring | nullrequired
  • replacesobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • filled_byobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • filled_onstring | nullrequired
  • can_reopenbooleanrequired
  • requestobject | nullrequired
    4 fields
    • byobject | nullrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • atstringrequired
    • notestring | nullrequired
    • withdrawnbooleanrequired
  • title_descriptionstring | nullrequired
  • customobject[]required
    7 fields
    • keystringrequired
    • labelstringrequired
    • typestring (enum)required

      One of: text, number, date, select, boolean, file, person, table.

    • tier"public" | "job" | "private"required
    • valuestring | number | boolean | object[]required

      For type file: the document id (download it with documents_download or documents_me_download); over an API key or MCP, "attached" for someone else's file. For type person: the person id. For type table: the rows, [{ <column key>: value }] (columns in org_fields_list).

    • fileobject | null

      Type file only: the file, or null when none is attached.

      4 fields
      • namestring | nullrequired

        The file name; null over an API key or MCP for someone else's file.

      • sizeintegerrequired
      • content_typestringrequired
      • previewablebooleanrequired

        The web app can show it (PDF, PNG, JPEG, WebP).

    • personobject | null

      Type person only: who it names (null when not set, or not someone you may see).

      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
  • approvalobject | nullrequired
    7 fields
    • state"pending" | "approved" | "rejected" | "withdrawn"required
    • reasons"always" | "over_plan" | "above_band"[]required

      Why it needed approval: always, new headcount over the plan, pay above the band.

    • target_status"open" | "on_hold"required
    • asked_byobject | nullrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • asked_atstringrequired
    • stepsobject[]required
      8 fields
      • kind"manager" | "hr" | "role" | "person"required
      • labelstringrequired

        Who decides it: the manager, HR, a role or a person.

      • state"waiting" | "pending" | "approved" | "rejected"required
      • byobject | nullrequired
        4 fields
        • idstringrequired
        • namestringrequired
        • titlestring | nullrequired
        • photo_urlstring | nullrequired
      • atstring | nullrequired
      • commentstring | nullrequired
      • autobooleanrequired

        Approved by itself: nobody but the proposer could decide it (noted).

      • fallbackbooleanrequired

        HR decides in place of the step's own approver, who could not.

    • closed_atstring | nullrequired
  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/positions.reopen \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"position_id":"pos1"}'
Response
{
  "data": {
    "id": "pos1",
    "title": "Data Engineer",
    "title_id": "t2",
    "status": "open",
    "reason": "replacement",
    "unit": {
      "id": "u2",
      "name": "Engineering"
    },
    "location": {
      "id": "l1",
      "name": "Lisbon"
    },
    "legal_entity": {
      "id": "e1",
      "name": "Acme Lda"
    },
    "reports_to_person": {
      "id": "p1",
      "name": "Ana Ferreira",
      "title": "CTO",
      "photo_url": null
    },
    "reports_to_position": null,
    "contract_type": "permanent",
    "weekly_hours": 40,
    "pay_range": null,
    "pay_range_hidden": true,
    "target_start_date": "2026-12-01",
    "notes": "Budget approved in Q3",
    "replaces": {
      "id": "p3",
      "name": "Rui Costa",
      "title": "Data Engineer",
      "photo_url": null
    },
    "filled_by": null,
    "filled_on": null,
    "can_reopen": false,
    "request": {
      "by": {
        "id": "p2",
        "name": "Tomás Silva",
        "title": "Engineering Manager",
        "photo_url": null
      },
      "at": "2026-10-03T09:00:00.000Z",
      "note": "Rui leaves at the end of November.",
      "withdrawn": false
    },
    "title_description": "Builds and runs the data pipelines the company reports from.",
    "custom": [
      {
        "key": "hiring_manager",
        "label": "Hiring manager",
        "type": "person",
        "tier": "public",
        "value": "p1",
        "person": {
          "id": "p1",
          "name": "Ana Ferreira",
          "title": "CTO",
          "photo_url": null
        }
      }
    ],
    "approval": null,
    "created_at": "2026-10-04T10:00:00.000Z",
    "updated_at": "2026-10-04T10:00:00.000Z"
  }
}

Get the approval rule for opening positions#

POST/v1/org/positions.approval_rule.getRead

Settings → Approval rules → Opening a position: when opening a position (a headcount request) needs approval — off (default), always, over_plan (only new headcount above the team's headcount budget for its target month; replacements never), above_band (a pay range above the band of its title), over_plan_or_above_band — and who approves, in order (manager, hr, a role, a named person). Owners, admins and HR.

Who can call it
Manage key owner admin hr
MCP tool
org_positions_approval_rule_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • when"off" | "always" | "over_plan" | "above_band" | "over_plan_or_above_band"required

    off (default: positions open at once), always, over_plan (only new headcount above the team's headcount budget for its target month), above_band (only a pay range above the pay band of its title), over_plan_or_above_band.

  • stepsobject[]required

    Who approves, in order.

    4 fields
    • kind"manager" | "hr" | "role" | "person"required

      manager: the person the position reports to (their own manager when they asked for it); hr: an owner, admin or HR member; role: anyone with a custom role (role_id, platform_roles_list); person: one named person (person_id), e.g. the finance director.

    • role_idstring | nullrequired
    • person_idstring | nullrequired
    • labelstringrequired

      Who decides, in words.

  • updated_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/positions.approval_rule.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "when": "over_plan",
    "steps": [
      {
        "kind": "manager",
        "role_id": null,
        "person_id": null,
        "label": "The manager it reports to"
      },
      {
        "kind": "person",
        "role_id": null,
        "person_id": "p6",
        "label": "Marta Rocha"
      }
    ],
    "updated_at": "2026-10-04T10:00:00.000Z"
  }
}

Change the approval rule for opening positions#

POST/v1/org/positions.approval_rule.updateWrite

Sets when opening a position needs approval (when: off, always, over_plan, above_band, over_plan_or_above_band) and who approves, in order (steps, 1 to 5: manager, hr, role with role_id, person with person_id). Positions already waiting keep their steps. Owners and admins, in the app only (never over an API key or MCP, so an assistant can never switch approval off).

Web app only
Refused for API keys and connected apps. Who approves new positions is set in the app only, so an assistant can never switch approval off.
MCP tool
org_positions_approval_rule_update on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • when"off" | "always" | "over_plan" | "above_band" | "over_plan_or_above_band"required
  • stepsobject[]required

    1–5 items.

    3 fields
    • kind"manager" | "hr" | "role" | "person"required
    • role_idstring | null

      1–100 characters.

    • person_idstring | null

      1–100 characters.

Returns

  • when"off" | "always" | "over_plan" | "above_band" | "over_plan_or_above_band"required

    off (default: positions open at once), always, over_plan (only new headcount above the team's headcount budget for its target month), above_band (only a pay range above the pay band of its title), over_plan_or_above_band.

  • stepsobject[]required

    Who approves, in order.

    4 fields
    • kind"manager" | "hr" | "role" | "person"required

      manager: the person the position reports to (their own manager when they asked for it); hr: an owner, admin or HR member; role: anyone with a custom role (role_id, platform_roles_list); person: one named person (person_id), e.g. the finance director.

    • role_idstring | nullrequired
    • person_idstring | nullrequired
    • labelstringrequired

      Who decides, in words.

  • updated_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/positions.approval_rule.update \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "when": "over_plan_or_above_band",
  "steps": [
    {
      "kind": "manager"
    },
    {
      "kind": "role",
      "role_id": "r1"
    },
    {
      "kind": "person",
      "person_id": "p6",
      "role_id": null
    }
  ]
}'
Response
{
  "data": {
    "when": "over_plan_or_above_band",
    "steps": [
      {
        "kind": "manager",
        "role_id": null,
        "person_id": null,
        "label": "The manager it reports to"
      },
      {
        "kind": "person",
        "role_id": null,
        "person_id": "p6",
        "label": "Marta Rocha"
      }
    ],
    "updated_at": "2026-10-04T10:00:00.000Z"
  }
}

Positions waiting for approval#

POST/v1/org/positions.requestsRead

Requests to open a position (headcount requests) under Settings → Approval rules → Opening a position: status open (default: waiting), decided (approved, rejected, withdrawn; newest 100) or all; waiting_for_me only those you can decide now; unit_id narrows to a team. Each has the position (title, team, location, who it reports to, target start), why it needs approval (always, over_plan, above_band), the steps with who decided, who can decide now, and — for its approvers and owners, admins and HR, in the app — the numbers: the pay range, the band of its title and the team's headcount budget against people, open and requested positions. Owners, admins and HR see every request; others the ones they asked for or approve. Deciding is in the app (org_positions_decide refuses API keys and MCP).

Who can call it
Manage key any Manage role
Me key anyone
MCP tool
org_positions_requests on HR Assistant, My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • status"open" | "decided" | "all"

    Default "open".

  • waiting_for_meboolean
  • unit_idstring

    1–100 characters.

Returns

  • itemsobject[]required
    7 fields
    • positionobjectrequired
      10 fields
      • idstringrequired
      • titlestringrequired
      • reason"new" | "replacement"required
      • unitobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • locationobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • reports_toobject | nullrequired
        4 fields
        • idstringrequired
        • namestringrequired
        • titlestring | nullrequired
        • photo_urlstring | nullrequired
      • target_start_datestring | nullrequired
      • contract_typestring | nullrequired
      • weekly_hoursnumber | nullrequired
      • statusstringrequired
    • approvalobjectrequired
      7 fields
      • state"pending" | "approved" | "rejected" | "withdrawn"required
      • reasons"always" | "over_plan" | "above_band"[]required
      • target_status"open" | "on_hold"required
      • asked_byobject | nullrequired
        4 fields
        • idstringrequired
        • namestringrequired
        • titlestring | nullrequired
        • photo_urlstring | nullrequired
      • asked_atstringrequired
      • closed_atstring | nullrequired
      • stepsobject[]required
        8 fields
        • kind"manager" | "hr" | "role" | "person"required
        • labelstringrequired
        • state"waiting" | "pending" | "approved" | "rejected"required
        • byobject | nullrequired
          4 fields
          • idstringrequired
          • namestringrequired
          • titlestring | nullrequired
          • photo_urlstring | nullrequired
        • atstring | nullrequired
        • commentstring | nullrequired
        • autobooleanrequired
        • fallbackbooleanrequired
    • impactobject | nullrequired

      The numbers when asked (pay tier): approvers and owners, admins and HR, in the app; null for others.

      4 fields
      • budgetobject | nullrequired

        The plan of its team (or the nearest team above it with one) for its target month; null without a plan.

        8 fields
        • unitobjectrequired
          2 fields
          • idstringrequired
          • namestringrequired
        • monthstringrequired
        • headcountintegerrequired

          The headcount budget in force.

        • actualintegerrequired
        • openintegerrequired
        • requestedintegerrequired

          Other positions waiting for approval there.

        • afterintegerrequired

          actual + open + requested + this one.

        • overbooleanrequired
      • payobject | nullrequired
        4 fields
        • minnumberrequired
        • maxnumberrequired
        • currencystringrequired
        • period"year" | "month" | "hour"required
      • bandobject | nullrequired
        4 fields
        • minnumberrequired
        • maxnumberrequired
        • currencystringrequired
        • period"year" | "month" | "hour"required
      • above_bandbooleanrequired
    • stepinteger | nullrequired

      The open step (null when decided).

    • waiting_forstring[]required

      Who can decide the open step now (names).

    • can_decidebooleanrequired
    • can_withdrawbooleanrequired
  • waiting_for_meintegerrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/positions.requests \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"all","waiting_for_me":true,"unit_id":"u2"}'
Response
{
  "data": {
    "items": [
      {
        "position": {
          "id": "pos1",
          "title": "Data Engineer",
          "reason": "new",
          "unit": {
            "id": "u2",
            "name": "Engineering"
          },
          "location": {
            "id": "l1",
            "name": "Lisbon"
          },
          "reports_to": {
            "id": "p1",
            "name": "Ana Ferreira",
            "title": "CTO",
            "photo_url": null
          },
          "target_start_date": "2026-12-01",
          "contract_type": "permanent",
          "weekly_hours": 40,
          "status": "draft"
        },
        "approval": {
          "state": "pending",
          "reasons": [
            "over_plan"
          ],
          "target_status": "open",
          "asked_by": {
            "id": "p2",
            "name": "Tomás Silva",
            "title": "Engineering Manager",
            "photo_url": null
          },
          "asked_at": "2026-10-04T10:00:00.000Z",
          "steps": [
            {
              "kind": "manager",
              "label": "The manager it reports to",
              "state": "pending",
              "by": null,
              "at": null,
              "comment": null,
              "auto": false,
              "fallback": false
            },
            {
              "kind": "person",
              "label": "Marta Rocha",
              "state": "waiting",
              "by": null,
              "at": null,
              "comment": null,
              "auto": false,
              "fallback": false
            }
          ],
          "closed_at": null
        },
        "impact": {
          "budget": {
            "unit": {
              "id": "u2",
              "name": "Engineering"
            },
            "month": "2026-12",
            "headcount": 8,
            "actual": 7,
            "open": 1,
            "requested": 0,
            "after": 9,
            "over": true
          },
          "pay": {
            "min": 40000,
            "max": 52000,
            "currency": "EUR",
            "period": "year"
          },
          "band": {
            "min": 38000,
            "max": 50000,
            "currency": "EUR",
            "period": "year"
          },
          "above_band": true
        },
        "step": 0,
        "waiting_for": [
          "Ana Ferreira"
        ],
        "can_decide": true,
        "can_withdraw": false
      }
    ],
    "waiting_for_me": 1
  }
}

Approve or reject opening a position#

POST/v1/org/positions.decideWrite

Decides the open step of a request to open a position (org_positions_requests): approve (the next step's approvers are asked; after the last one the position opens with the status asked for, open or on hold) or reject with a comment saying why (the position is cancelled and keeps the reason; whoever asked is emailed). Only the step's approvers, never the person who asked. In the app only: refused over an API key or MCP.

Web app only
Refused for API keys and connected apps. Approving a position needs a person signed in to Bizisy.
MCP tool
org_positions_decide on HR Assistant, My Workplace
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • position_idstringrequired

    1–100 characters.

  • decision"approve" | "reject"required
  • commentstring

    Up to 500 characters.

  • stepinteger

    The step you saw: refused when the request moved on meanwhile.

    From 0 to 5.

Returns

7 fields
  • positionobjectrequired
    10 fields
    • idstringrequired
    • titlestringrequired
    • reason"new" | "replacement"required
    • unitobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • locationobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • reports_toobject | nullrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • target_start_datestring | nullrequired
    • contract_typestring | nullrequired
    • weekly_hoursnumber | nullrequired
    • statusstringrequired
  • approvalobjectrequired
    7 fields
    • state"pending" | "approved" | "rejected" | "withdrawn"required
    • reasons"always" | "over_plan" | "above_band"[]required
    • target_status"open" | "on_hold"required
    • asked_byobject | nullrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • asked_atstringrequired
    • closed_atstring | nullrequired
    • stepsobject[]required
      8 fields
      • kind"manager" | "hr" | "role" | "person"required
      • labelstringrequired
      • state"waiting" | "pending" | "approved" | "rejected"required
      • byobject | nullrequired
        4 fields
        • idstringrequired
        • namestringrequired
        • titlestring | nullrequired
        • photo_urlstring | nullrequired
      • atstring | nullrequired
      • commentstring | nullrequired
      • autobooleanrequired
      • fallbackbooleanrequired
  • impactobject | nullrequired

    The numbers when asked (pay tier): approvers and owners, admins and HR, in the app; null for others.

    4 fields
    • budgetobject | nullrequired

      The plan of its team (or the nearest team above it with one) for its target month; null without a plan.

      8 fields
      • unitobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • monthstringrequired
      • headcountintegerrequired

        The headcount budget in force.

      • actualintegerrequired
      • openintegerrequired
      • requestedintegerrequired

        Other positions waiting for approval there.

      • afterintegerrequired

        actual + open + requested + this one.

      • overbooleanrequired
    • payobject | nullrequired
      4 fields
      • minnumberrequired
      • maxnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
    • bandobject | nullrequired
      4 fields
      • minnumberrequired
      • maxnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
    • above_bandbooleanrequired
  • stepinteger | nullrequired

    The open step (null when decided).

  • waiting_forstring[]required

    Who can decide the open step now (names).

  • can_decidebooleanrequired
  • can_withdrawbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/positions.decide \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "position_id": "pos1",
  "decision": "reject",
  "comment": "Not in this year'\''s budget",
  "step": 1
}'
Response
{
  "data": {
    "position": {
      "id": "pos1",
      "title": "Data Engineer",
      "reason": "new",
      "unit": {
        "id": "u2",
        "name": "Engineering"
      },
      "location": {
        "id": "l1",
        "name": "Lisbon"
      },
      "reports_to": {
        "id": "p1",
        "name": "Ana Ferreira",
        "title": "CTO",
        "photo_url": null
      },
      "target_start_date": "2026-12-01",
      "contract_type": "permanent",
      "weekly_hours": 40,
      "status": "draft"
    },
    "approval": {
      "state": "pending",
      "reasons": [
        "over_plan"
      ],
      "target_status": "open",
      "asked_by": {
        "id": "p2",
        "name": "Tomás Silva",
        "title": "Engineering Manager",
        "photo_url": null
      },
      "asked_at": "2026-10-04T10:00:00.000Z",
      "steps": [
        {
          "kind": "manager",
          "label": "The manager it reports to",
          "state": "approved",
          "by": {
            "id": "p1",
            "name": "Ana Ferreira",
            "title": "CTO",
            "photo_url": null
          },
          "at": "2026-10-05T09:00:00.000Z",
          "comment": null,
          "auto": false,
          "fallback": false
        },
        {
          "kind": "person",
          "label": "Marta Rocha",
          "state": "pending",
          "by": null,
          "at": null,
          "comment": null,
          "auto": false,
          "fallback": false
        }
      ],
      "closed_at": null
    },
    "impact": {
      "budget": {
        "unit": {
          "id": "u2",
          "name": "Engineering"
        },
        "month": "2026-12",
        "headcount": 8,
        "actual": 7,
        "open": 1,
        "requested": 0,
        "after": 9,
        "over": true
      },
      "pay": {
        "min": 40000,
        "max": 52000,
        "currency": "EUR",
        "period": "year"
      },
      "band": {
        "min": 38000,
        "max": 50000,
        "currency": "EUR",
        "period": "year"
      },
      "above_band": true
    },
    "step": 1,
    "waiting_for": [
      "Ana Ferreira"
    ],
    "can_decide": true,
    "can_withdraw": false
  }
}

Headcount budgets#

POST/v1/org/budgets.listRead

Headcount budget against actual per team on as_of (default today): a budget covers the team and every team below it, from its from_month until the team's next budget. For every live team with a budget (or, with include_all, every live team): budget in force, the next one, actual headcount and FTE employed on that day, open positions (status open, only when as_of is today), remaining (budget − actual − open) and status (over, over_with_open, on_budget, room). totals sums the top-level budgeted teams only (a team inside a budgeted department is part of the department's number). Owners, admins and HR; never a custom role. Part of the Reports & analytics module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).

Who can call it
Manage key owner admin hr
MCP tool
org_budgets_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • as_ofstring
  • include_allboolean

    Default false.

Returns

  • as_ofstringrequired
  • monthstringrequired
  • teamsobject[]required
    8 fields
    • unitobjectrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • kindstringrequired
      • parent_idstring | nullrequired
    • budgetobject | nullrequired

      The budget in force on as_of (null: none yet; next says when one starts).

      4 fields
      • from_monthstringrequired
      • headcountintegerrequired
      • ftenumber | nullrequired
      • notestring | nullrequired
    • nextobject | nullrequired

      The next budget row after as_of, if any.

      4 fields
      • from_monthstringrequired
      • headcountintegerrequired
      • ftenumber | nullrequired
      • notestring | nullrequired
    • actualobjectrequired

      People employed on as_of in this team and every team below it.

      2 fields
      • headcountintegerrequired
      • ftenumberrequired
    • openintegerrequired

      Open positions (status open; drafts and on-hold roles are not counted) in this team and below; only when as_of is today, else 0.

    • remaininginteger | nullrequired

      budget − actual − open: places left to plan; negative when over. null without a budget.

    • status"over" | "over_with_open" | "on_budget" | "room"required

      over (more people than budgeted), over_with_open (filling the open roles would pass it), on_budget, room; null without a budget.

    • historyobject[]required

      Every budget row of this team, oldest first.

      4 fields
      • from_monthstringrequired
      • headcountintegerrequired
      • ftenumber | nullrequired
      • notestring | nullrequired
  • totalsobjectrequired
    5 fields
    • budgetintegerrequired
    • actualintegerrequired
    • openintegerrequired
    • remainingintegerrequired
    • overintegerrequired

      Budgeted teams over their budget.

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/budgets.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"as_of":"2026-12-31","include_all":true}'
Response
{
  "data": {
    "as_of": "2026-12-31",
    "month": "2026-10",
    "teams": [
      {
        "unit": {
          "id": "u2",
          "name": "Engineering",
          "kind": "department",
          "parent_id": "u1"
        },
        "budget": {
          "from_month": "2026-01",
          "headcount": 8,
          "fte": null,
          "note": "FY26 plan"
        },
        "next": null,
        "actual": {
          "headcount": 6,
          "fte": 5.5
        },
        "open": 2,
        "remaining": 0,
        "status": "on_budget",
        "history": [
          {
            "from_month": "2026-01",
            "headcount": 8,
            "fte": null,
            "note": "FY26 plan"
          }
        ]
      }
    ],
    "totals": {
      "budget": 8,
      "actual": 6,
      "open": 2,
      "remaining": 0,
      "over": 0
    }
  }
}

Set a headcount budget#

POST/v1/org/budgets.setWrite

Sets a team's headcount budget from from_month (YYYY-MM; default this month) on: headcount (people, 0–10000), optionally fte and a note (at most 300 characters). It holds until the team's next budget row; setting the same month again replaces that row. A budget covers the team and every team below it. Owners, admins and HR; never a custom role. Part of the Reports & analytics module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).

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

Input

  • unit_idstringrequired
  • from_monthstring

    Pattern ^\d{4}-(0[1-9]|1[0-2])$.

  • headcountintegerrequired

    From 0 to 10000.

  • ftenumber | null

    From 0 to 10000.

  • notestring | null

    Up to 300 characters.

Returns

  • unit_idstringrequired
  • unit_namestringrequired
  • replacedbooleanrequired
  • rowobjectrequired
    4 fields
    • from_monthstringrequired
    • headcountintegerrequired
    • ftenumber | nullrequired
    • notestring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/budgets.set \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "unit_id": "u2",
  "from_month": "2027-01",
  "headcount": 10,
  "fte": 9.5,
  "note": "FY27 plan"
}'
Response
{
  "data": {
    "unit_id": "u2",
    "unit_name": "Engineering",
    "replaced": false,
    "row": {
      "from_month": "2026-10",
      "headcount": 8,
      "fte": null,
      "note": null
    }
  }
}

Remove a headcount budget#

POST/v1/org/budgets.removeWrite

Removes a team's budget row for from_month (YYYY-MM). The row before it (if any) then holds on. Owners, admins and HR; never a custom role. Part of the Reports & analytics module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).

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

Input

  • unit_idstringrequired
  • from_monthstringrequired

    Pattern ^\d{4}-(0[1-9]|1[0-2])$.

Returns

  • unit_idstringrequired
  • from_monthstringrequired
  • removedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/budgets.remove \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"unit_id":"u2","from_month":"2027-01"}'
Response
{
  "data": {
    "unit_id": "u2",
    "from_month": "2027-01",
    "removed": true
  }
}

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

Developer docs