Skip to content

API reference

Approvals

Approval rules and change requests: list, approve, reject and withdraw.

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

Get approval settings#

POST/v1/org/approvals.settings.getRead

Returns who must approve each kind of change before it takes effect: job_change (title, team, manager, location, legal entity, employment type, FTE, contract terms; org_people_change_job), termination (org_people_terminate) and pay_change (org_pay_add). Modes: off (no approval: the change applies at once; the default), hr (an owner, admin or HR member), manager (the person's manager today; when they have no manager, the team lead of their team or of a team above it decides; HR when no one of them can sign in, or when the manager proposed the change), manager_then_hr (both, in that order). Pay offers off and hr only. hr_approvers is how many owners, admins and HR members can approve. Owners, admins and HR.

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

Input

No input: send {}.

Returns

  • job_change"off" | "hr" | "manager" | "manager_then_hr"required
  • termination"off" | "hr" | "manager" | "manager_then_hr"required
  • pay_change"off" | "hr" | "manager" | "manager_then_hr"required
  • updated_atstring | nullrequired
  • hr_approversintegerrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/approvals.settings.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "job_change": "off",
    "termination": "off",
    "pay_change": "off",
    "updated_at": null,
    "hr_approvers": 2
  }
}

Change approval settings#

POST/v1/org/approvals.settings.updateWrite

Sets who approves each kind of change (see org_approvals_settings_get): job_change, termination and pay_change, each off, hr, manager or manager_then_hr (pay: off or hr). Send only what changes. Requests already waiting keep the steps they were created with. Owners and admins only, and only in the app: 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 changes is set in the app only, so an assistant can never switch approval off.
MCP tool
org_approvals_settings_update on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • job_change"off" | "hr" | "manager" | "manager_then_hr"
  • termination"off" | "hr" | "manager" | "manager_then_hr"
  • pay_change"off" | "hr"

Returns

  • job_change"off" | "hr" | "manager" | "manager_then_hr"required
  • termination"off" | "hr" | "manager" | "manager_then_hr"required
  • pay_change"off" | "hr" | "manager" | "manager_then_hr"required
  • updated_atstring | nullrequired
  • hr_approversintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/approvals.settings.update \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"termination":"manager","pay_change":"hr"}'
Response
{
  "data": {
    "job_change": "manager_then_hr",
    "termination": "manager",
    "pay_change": "hr",
    "updated_at": "2026-10-04T10:00:00.000Z",
    "hr_approvers": 2
  }
}

List approval requests#

POST/v1/org/approvals.listRead

Lists change requests you may see: status open (default: waiting for a decision), closed (approved, rejected, withdrawn, outdated or expired; newest first, at most 100) or all; person_id narrows to one person; waiting_for_me only those you can decide now. waiting_for_me in the result counts requests you can decide (over an API key: that its user can decide in the app). Each request has the change (job_change before/after, termination last day and reason, or pay_change amount), the effective date, the steps with who approved or can approve, and can_decide. You see job and termination requests as HR, as one of the person's managers, as the proposer, or as the team lead deciding it (while it waits for you, and after you decided); pay requests only as HR in the app; never requests about yourself. Approving needs the app (org_approvals_approve refuses API keys).

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

Input

  • status"open" | "closed" | "all"

    Default "open".

  • person_idstring
  • waiting_for_meboolean

Returns

  • itemsobject[]required
    23 fields
    • idstringrequired
    • kind"job_change" | "termination" | "pay_change"required
    • status"pending" | "approved" | "rejected" | "cancelled" | "outdated" | "expired"required
    • personobjectrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • effective_datestringrequired
    • expires_onstringrequired
    • changestring (enum)required

      One of: change_job, terminate, pay_add, correct_job, rehire, pay_remove, leave, promote, probation, profile_title, details.

    • job_changeobject | nullrequired
      3 fields
      • reason"change" | "promotion" | "transfer" | "correction" | "rehire"required
      • beforeobject | nullrequired
        23 fields
        • idstringrequired
        • valid_fromstringrequired
        • valid_tostring | nullrequired
        • titlestringrequired

          The job title as the catalog names it now (reports and grouping use this).

        • title_idstring | nullrequired

          The catalog title (org_titles_list); null while not in the catalog yet.

        • display_titlestring | nullrequired

          A different title shown on the profile, chart and directory; null: the catalog title.

        • unitobject | nullrequired
          2 fields
          • idstringrequired
          • namestringrequired
        • managerobject | nullrequired
          4 fields
          • idstringrequired
          • namestringrequired
          • titlestring | nullrequired
          • photo_urlstring | nullrequired
        • locationobject | nullrequired
          2 fields
          • idstringrequired
          • namestringrequired
        • legal_entityobject | nullrequired
          2 fields
          • idstringrequired
          • namestringrequired
        • employment_type"full_time" | "part_time" | "contractor" | "intern"required
        • ftenumberrequired
        • reasonstringrequired
        • end_reasonstring | nullrequired
        • leaving_typestring (enum)required

          Why the employment ended (structured); null: not recorded or still employed.

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

        • toldboolean | nullrequired

          With a termination (end_reason): whether the person has been told about this last day; false: only HR and their manager know, until org_people_mark_told or the day passes. null on other rows.

        • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
        • contract_end_datestring | nullrequired
        • probation_end_datestring | nullrequired
        • weekly_hoursnumber | nullrequired
        • notice_period_daysinteger | nullrequired
        • customobject[]required

          Job custom fields (target job) on this row, effective-dated: each job row keeps its own values. Only for those who see the job details.

          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.

          • personobject | null

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

        • regrettedboolean | null

          Private (people analytics): on the row a voluntary termination ends, whether HR marked the leaver as regretted (null: not set). Only owners, admins and HR in the app see it; absent for everyone else.

      • afterobjectrequired
        23 fields
        • idstringrequired
        • valid_fromstringrequired
        • valid_tostring | nullrequired
        • titlestringrequired

          The job title as the catalog names it now (reports and grouping use this).

        • title_idstring | nullrequired

          The catalog title (org_titles_list); null while not in the catalog yet.

        • display_titlestring | nullrequired

          A different title shown on the profile, chart and directory; null: the catalog title.

        • unitobject | nullrequired
          2 fields
          • idstringrequired
          • namestringrequired
        • managerobject | nullrequired
          4 fields
          • idstringrequired
          • namestringrequired
          • titlestring | nullrequired
          • photo_urlstring | nullrequired
        • locationobject | nullrequired
          2 fields
          • idstringrequired
          • namestringrequired
        • legal_entityobject | nullrequired
          2 fields
          • idstringrequired
          • namestringrequired
        • employment_type"full_time" | "part_time" | "contractor" | "intern"required
        • ftenumberrequired
        • reasonstringrequired
        • end_reasonstring | nullrequired
        • leaving_typestring (enum)required

          Why the employment ended (structured); null: not recorded or still employed.

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

        • toldboolean | nullrequired

          With a termination (end_reason): whether the person has been told about this last day; false: only HR and their manager know, until org_people_mark_told or the day passes. null on other rows.

        • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
        • contract_end_datestring | nullrequired
        • probation_end_datestring | nullrequired
        • weekly_hoursnumber | nullrequired
        • notice_period_daysinteger | nullrequired
        • customobject[]required

          Job custom fields (target job) on this row, effective-dated: each job row keeps its own values. Only for those who see the job details.

          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.

          • personobject | null

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

        • regrettedboolean | null

          Private (people analytics): on the row a voluntary termination ends, whether HR marked the leaver as regretted (null: not set). Only owners, admins and HR in the app see it; absent for everyone else.

    • terminationobject | nullrequired
      6 fields
      • last_daystringrequired
      • reasonstring | nullrequired
      • leaving_typestring (enum)required

        The leaving type the request records (null: none given; a moved termination keeps its own).

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

      • person_toldboolean | nullrequired

        Whether the request says the person has been told (null: not said; the default for its leaving type applies).

      • jobobject | nullrequired
        23 fields
        • idstringrequired
        • valid_fromstringrequired
        • valid_tostring | nullrequired
        • titlestringrequired

          The job title as the catalog names it now (reports and grouping use this).

        • title_idstring | nullrequired

          The catalog title (org_titles_list); null while not in the catalog yet.

        • display_titlestring | nullrequired

          A different title shown on the profile, chart and directory; null: the catalog title.

        • unitobject | nullrequired
          2 fields
          • idstringrequired
          • namestringrequired
        • managerobject | nullrequired
          4 fields
          • idstringrequired
          • namestringrequired
          • titlestring | nullrequired
          • photo_urlstring | nullrequired
        • locationobject | nullrequired
          2 fields
          • idstringrequired
          • namestringrequired
        • legal_entityobject | nullrequired
          2 fields
          • idstringrequired
          • namestringrequired
        • employment_type"full_time" | "part_time" | "contractor" | "intern"required
        • ftenumberrequired
        • reasonstringrequired
        • end_reasonstring | nullrequired
        • leaving_typestring (enum)required

          Why the employment ended (structured); null: not recorded or still employed.

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

        • toldboolean | nullrequired

          With a termination (end_reason): whether the person has been told about this last day; false: only HR and their manager know, until org_people_mark_told or the day passes. null on other rows.

        • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
        • contract_end_datestring | nullrequired
        • probation_end_datestring | nullrequired
        • weekly_hoursnumber | nullrequired
        • notice_period_daysinteger | nullrequired
        • customobject[]required

          Job custom fields (target job) on this row, effective-dated: each job row keeps its own values. Only for those who see the job details.

          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.

          • personobject | null

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

        • regrettedboolean | null

          Private (people analytics): on the row a voluntary termination ends, whether HR marked the leaver as regretted (null: not set). Only owners, admins and HR in the app see it; absent for everyone else.

      • change"end" | "move" | "cancel"required
    • pay_changeobject | nullrequired
      6 fields
      • amountnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
      • notestring | nullrequired
      • beforeobject | nullrequired
        4 fields
        • amountnumberrequired
        • currencystringrequired
        • periodstringrequired
        • valid_fromstringrequired
      • removesbooleanrequired
    • probationobject | nullrequired
      2 fields
      • outcome"passed" | "extend"required
      • probation_end_datestringrequired
    • includes_paybooleanrequired
    • leaveobject | nullrequired
      3 fields
      • reassignobject[]required
        2 fields
        • personobjectrequired
          4 fields
          • idstringrequired
          • namestringrequired
          • titlestring | nullrequired
          • photo_urlstring | nullrequired
        • managerobject | nullrequired
          4 fields
          • idstringrequired
          • namestringrequired
          • titlestring | nullrequired
          • photo_urlstring | nullrequired
      • access"after_last_day" | "now" | "keep"required
      • replacement_positionbooleanrequired
    • proposed_byobjectrequired
      3 fields
      • namestringrequired
      • person_idstring | nullrequired
      • via"app" | "api"required
    • proposed_atstringrequired
    • stepsobject[]required
      11 fields
      • role"manager" | "hr"required
      • state"waiting" | "pending" | "approved" | "rejected"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
      • decided_byobject | nullrequired
        2 fields
        • namestringrequired
        • person_idstring | nullrequired
      • decided_atstring | nullrequired
      • commentstring | nullrequired
      • auto"proposed_by_approver" | "no_other_approver"required
      • approversobject[]required
        3 fields
        • namestringrequired
        • person_idstring | nullrequired
        • is_viewerbooleanrequired
    • closed_atstring | nullrequired
    • closed_byobject | nullrequired
      2 fields
      • namestringrequired
      • person_idstring | nullrequired
    • can_decidebooleanrequired
    • can_cancelbooleanrequired
    • is_proposerbooleanrequired
    • can_rejectbooleanrequired
    • decide_urlstringrequired

      Where to open (and, for approvers, decide) this request in Bizisy: a path on the company address (https://<slug>.bizisy.com + decide_url), for the app of this call (Manage or My workspace). Approving and rejecting happen there, never over MCP or an API key.

  • waiting_for_meintegerrequired

    Everything waiting for your decision: these change requests plus the contributions below.

  • contributionsobject[]required

    Other requests in the shared inbox (time off: timeoff_requests_list with waiting_for_me true; time corrections: timeclock_corrections_list with waiting_for_me true; job offers: hiring_offers_list with waiting_for_me true; document templates: documents_templates_approvals; shift swaps and claims: shifts_requests_list with scope to_decide; positions to open: org_positions_requests with waiting_for_me true).

    2 fields
    • source"time_off" | "time_clock" | "hiring" | "documents" | "shifts" | "positions"required
    • waiting_for_meintegerrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/approvals.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"closed","person_id":"p1"}'
Response
{
  "data": {
    "items": [
      {
        "id": "apr1",
        "kind": "job_change",
        "status": "pending",
        "decide_url": "/manage/approvals/apr1",
        "person": {
          "id": "p1",
          "name": "Ana Ferreira",
          "title": "Engineer",
          "photo_url": null
        },
        "effective_date": "2026-11-01",
        "expires_on": "2026-12-01",
        "change": "change_job",
        "job_change": {
          "reason": "promotion",
          "before": {
            "id": "j1",
            "valid_from": "2024-01-15",
            "valid_to": null,
            "title": "Engineer",
            "title_id": "t1",
            "display_title": null,
            "unit": {
              "id": "u2",
              "name": "Engineering"
            },
            "manager": {
              "id": "p2",
              "name": "Rui Costa",
              "title": "CTO",
              "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
            },
            "location": {
              "id": "l1",
              "name": "Head office"
            },
            "legal_entity": {
              "id": "e1",
              "name": "Acme Lda"
            },
            "employment_type": "full_time",
            "fte": 1,
            "reason": "hire",
            "end_reason": null,
            "leaving_type": null,
            "told": null,
            "contract_type": "fixed_term",
            "contract_end_date": "2026-01-14",
            "probation_end_date": "2024-07-14",
            "weekly_hours": 40,
            "notice_period_days": 30,
            "custom": [
              {
                "key": "shift_pattern",
                "label": "Shift pattern",
                "type": "select",
                "tier": "job",
                "value": "Day"
              }
            ]
          },
          "after": {
            "id": "apr1:after",
            "valid_from": "2024-01-15",
            "valid_to": null,
            "title": "Senior Engineer",
            "title_id": "t1",
            "display_title": null,
            "unit": {
              "id": "u2",
              "name": "Engineering"
            },
            "manager": {
              "id": "p2",
              "name": "Rui Costa",
              "title": "CTO",
              "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
            },
            "location": {
              "id": "l1",
              "name": "Head office"
            },
            "legal_entity": {
              "id": "e1",
              "name": "Acme Lda"
            },
            "employment_type": "full_time",
            "fte": 1,
            "reason": "promotion",
            "end_reason": null,
            "leaving_type": null,
            "told": null,
            "contract_type": "fixed_term",
            "contract_end_date": "2026-01-14",
            "probation_end_date": "2024-07-14",
            "weekly_hours": 40,
            "notice_period_days": 30,
            "custom": [
              {
                "key": "shift_pattern",
                "label": "Shift pattern",
                "type": "select",
                "tier": "job",
                "value": "Day"
              }
            ]
          }
        },
        "termination": null,
        "pay_change": null,
        "probation": null,
        "includes_pay": false,
        "leave": null,
        "proposed_by": {
          "name": "Hugo Reis",
          "person_id": "p4",
          "via": "app"
        },
        "proposed_at": "2026-10-04T10:00:00.000Z",
        "steps": [
          {
            "role": "manager",
            "state": "pending",
            "fallback": false,
            "team_lead": null,
            "team_lead_blocked": null,
            "untrusted": null,
            "decided_by": null,
            "decided_at": null,
            "comment": null,
            "auto": null,
            "approvers": [
              {
                "name": "Bea Silva",
                "person_id": "p2",
                "is_viewer": true
              }
            ]
          }
        ],
        "closed_at": null,
        "closed_by": null,
        "can_decide": true,
        "can_cancel": false,
        "is_proposer": false,
        "can_reject": true
      }
    ],
    "waiting_for_me": 4,
    "contributions": [
      {
        "source": "time_off",
        "waiting_for_me": 2
      },
      {
        "source": "documents",
        "waiting_for_me": 1
      }
    ]
  }
}

Get an approval request#

POST/v1/org/approvals.getRead

Returns one change request (see org_approvals_list) with its change, steps, comments and whether you can decide or withdraw it.

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

Input

  • approval_idstringrequired

Returns

23 fields
  • idstringrequired
  • kind"job_change" | "termination" | "pay_change"required
  • status"pending" | "approved" | "rejected" | "cancelled" | "outdated" | "expired"required
  • personobjectrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • effective_datestringrequired
  • expires_onstringrequired
  • changestring (enum)required

    One of: change_job, terminate, pay_add, correct_job, rehire, pay_remove, leave, promote, probation, profile_title, details.

  • job_changeobject | nullrequired
    3 fields
    • reason"change" | "promotion" | "transfer" | "correction" | "rehire"required
    • beforeobject | nullrequired
      23 fields
      • idstringrequired
      • valid_fromstringrequired
      • valid_tostring | nullrequired
      • titlestringrequired

        The job title as the catalog names it now (reports and grouping use this).

      • title_idstring | nullrequired

        The catalog title (org_titles_list); null while not in the catalog yet.

      • display_titlestring | nullrequired

        A different title shown on the profile, chart and directory; null: the catalog title.

      • unitobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • managerobject | nullrequired
        4 fields
        • idstringrequired
        • namestringrequired
        • titlestring | nullrequired
        • photo_urlstring | nullrequired
      • locationobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • legal_entityobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • employment_type"full_time" | "part_time" | "contractor" | "intern"required
      • ftenumberrequired
      • reasonstringrequired
      • end_reasonstring | nullrequired
      • leaving_typestring (enum)required

        Why the employment ended (structured); null: not recorded or still employed.

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

      • toldboolean | nullrequired

        With a termination (end_reason): whether the person has been told about this last day; false: only HR and their manager know, until org_people_mark_told or the day passes. null on other rows.

      • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
      • contract_end_datestring | nullrequired
      • probation_end_datestring | nullrequired
      • weekly_hoursnumber | nullrequired
      • notice_period_daysinteger | nullrequired
      • customobject[]required

        Job custom fields (target job) on this row, effective-dated: each job row keeps its own values. Only for those who see the job details.

        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
      • regrettedboolean | null

        Private (people analytics): on the row a voluntary termination ends, whether HR marked the leaver as regretted (null: not set). Only owners, admins and HR in the app see it; absent for everyone else.

    • afterobjectrequired
      23 fields
      • idstringrequired
      • valid_fromstringrequired
      • valid_tostring | nullrequired
      • titlestringrequired

        The job title as the catalog names it now (reports and grouping use this).

      • title_idstring | nullrequired

        The catalog title (org_titles_list); null while not in the catalog yet.

      • display_titlestring | nullrequired

        A different title shown on the profile, chart and directory; null: the catalog title.

      • unitobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • managerobject | nullrequired
        4 fields
        • idstringrequired
        • namestringrequired
        • titlestring | nullrequired
        • photo_urlstring | nullrequired
      • locationobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • legal_entityobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • employment_type"full_time" | "part_time" | "contractor" | "intern"required
      • ftenumberrequired
      • reasonstringrequired
      • end_reasonstring | nullrequired
      • leaving_typestring (enum)required

        Why the employment ended (structured); null: not recorded or still employed.

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

      • toldboolean | nullrequired

        With a termination (end_reason): whether the person has been told about this last day; false: only HR and their manager know, until org_people_mark_told or the day passes. null on other rows.

      • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
      • contract_end_datestring | nullrequired
      • probation_end_datestring | nullrequired
      • weekly_hoursnumber | nullrequired
      • notice_period_daysinteger | nullrequired
      • customobject[]required

        Job custom fields (target job) on this row, effective-dated: each job row keeps its own values. Only for those who see the job details.

        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
      • regrettedboolean | null

        Private (people analytics): on the row a voluntary termination ends, whether HR marked the leaver as regretted (null: not set). Only owners, admins and HR in the app see it; absent for everyone else.

  • terminationobject | nullrequired
    6 fields
    • last_daystringrequired
    • reasonstring | nullrequired
    • leaving_typestring (enum)required

      The leaving type the request records (null: none given; a moved termination keeps its own).

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

    • person_toldboolean | nullrequired

      Whether the request says the person has been told (null: not said; the default for its leaving type applies).

    • jobobject | nullrequired
      23 fields
      • idstringrequired
      • valid_fromstringrequired
      • valid_tostring | nullrequired
      • titlestringrequired

        The job title as the catalog names it now (reports and grouping use this).

      • title_idstring | nullrequired

        The catalog title (org_titles_list); null while not in the catalog yet.

      • display_titlestring | nullrequired

        A different title shown on the profile, chart and directory; null: the catalog title.

      • unitobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • managerobject | nullrequired
        4 fields
        • idstringrequired
        • namestringrequired
        • titlestring | nullrequired
        • photo_urlstring | nullrequired
      • locationobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • legal_entityobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • employment_type"full_time" | "part_time" | "contractor" | "intern"required
      • ftenumberrequired
      • reasonstringrequired
      • end_reasonstring | nullrequired
      • leaving_typestring (enum)required

        Why the employment ended (structured); null: not recorded or still employed.

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

      • toldboolean | nullrequired

        With a termination (end_reason): whether the person has been told about this last day; false: only HR and their manager know, until org_people_mark_told or the day passes. null on other rows.

      • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
      • contract_end_datestring | nullrequired
      • probation_end_datestring | nullrequired
      • weekly_hoursnumber | nullrequired
      • notice_period_daysinteger | nullrequired
      • customobject[]required

        Job custom fields (target job) on this row, effective-dated: each job row keeps its own values. Only for those who see the job details.

        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
      • regrettedboolean | null

        Private (people analytics): on the row a voluntary termination ends, whether HR marked the leaver as regretted (null: not set). Only owners, admins and HR in the app see it; absent for everyone else.

    • change"end" | "move" | "cancel"required
  • pay_changeobject | nullrequired
    6 fields
    • amountnumberrequired
    • currencystringrequired
    • period"year" | "month" | "hour"required
    • notestring | nullrequired
    • beforeobject | nullrequired
      4 fields
      • amountnumberrequired
      • currencystringrequired
      • periodstringrequired
      • valid_fromstringrequired
    • removesbooleanrequired
  • probationobject | nullrequired
    2 fields
    • outcome"passed" | "extend"required
    • probation_end_datestringrequired
  • includes_paybooleanrequired
  • leaveobject | nullrequired
    3 fields
    • reassignobject[]required
      2 fields
      • personobjectrequired
        4 fields
        • idstringrequired
        • namestringrequired
        • titlestring | nullrequired
        • photo_urlstring | nullrequired
      • managerobject | nullrequired
        4 fields
        • idstringrequired
        • namestringrequired
        • titlestring | nullrequired
        • photo_urlstring | nullrequired
    • access"after_last_day" | "now" | "keep"required
    • replacement_positionbooleanrequired
  • proposed_byobjectrequired
    3 fields
    • namestringrequired
    • person_idstring | nullrequired
    • via"app" | "api"required
  • proposed_atstringrequired
  • stepsobject[]required
    11 fields
    • role"manager" | "hr"required
    • state"waiting" | "pending" | "approved" | "rejected"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
    • decided_byobject | nullrequired
      2 fields
      • namestringrequired
      • person_idstring | nullrequired
    • decided_atstring | nullrequired
    • commentstring | nullrequired
    • auto"proposed_by_approver" | "no_other_approver"required
    • approversobject[]required
      3 fields
      • namestringrequired
      • person_idstring | nullrequired
      • is_viewerbooleanrequired
  • closed_atstring | nullrequired
  • closed_byobject | nullrequired
    2 fields
    • namestringrequired
    • person_idstring | nullrequired
  • can_decidebooleanrequired
  • can_cancelbooleanrequired
  • is_proposerbooleanrequired
  • can_rejectbooleanrequired
  • decide_urlstringrequired

    Where to open (and, for approvers, decide) this request in Bizisy: a path on the company address (https://<slug>.bizisy.com + decide_url), for the app of this call (Manage or My workspace). Approving and rejecting happen there, never over MCP or an API key.

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/approvals.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"approval_id":"apr1"}'
Response
{
  "data": {
    "id": "apr1",
    "kind": "job_change",
    "status": "pending",
    "decide_url": "/manage/approvals/apr1",
    "person": {
      "id": "p1",
      "name": "Ana Ferreira",
      "title": "Engineer",
      "photo_url": null
    },
    "effective_date": "2026-11-01",
    "expires_on": "2026-12-01",
    "change": "change_job",
    "job_change": {
      "reason": "promotion",
      "before": {
        "id": "j1",
        "valid_from": "2024-01-15",
        "valid_to": null,
        "title": "Engineer",
        "title_id": "t1",
        "display_title": null,
        "unit": {
          "id": "u2",
          "name": "Engineering"
        },
        "manager": {
          "id": "p2",
          "name": "Rui Costa",
          "title": "CTO",
          "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
        },
        "location": {
          "id": "l1",
          "name": "Head office"
        },
        "legal_entity": {
          "id": "e1",
          "name": "Acme Lda"
        },
        "employment_type": "full_time",
        "fte": 1,
        "reason": "hire",
        "end_reason": null,
        "leaving_type": null,
        "told": null,
        "contract_type": "fixed_term",
        "contract_end_date": "2026-01-14",
        "probation_end_date": "2024-07-14",
        "weekly_hours": 40,
        "notice_period_days": 30,
        "custom": [
          {
            "key": "shift_pattern",
            "label": "Shift pattern",
            "type": "select",
            "tier": "job",
            "value": "Day"
          }
        ]
      },
      "after": {
        "id": "apr1:after",
        "valid_from": "2024-01-15",
        "valid_to": null,
        "title": "Senior Engineer",
        "title_id": "t1",
        "display_title": null,
        "unit": {
          "id": "u2",
          "name": "Engineering"
        },
        "manager": {
          "id": "p2",
          "name": "Rui Costa",
          "title": "CTO",
          "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
        },
        "location": {
          "id": "l1",
          "name": "Head office"
        },
        "legal_entity": {
          "id": "e1",
          "name": "Acme Lda"
        },
        "employment_type": "full_time",
        "fte": 1,
        "reason": "promotion",
        "end_reason": null,
        "leaving_type": null,
        "told": null,
        "contract_type": "fixed_term",
        "contract_end_date": "2026-01-14",
        "probation_end_date": "2024-07-14",
        "weekly_hours": 40,
        "notice_period_days": 30,
        "custom": [
          {
            "key": "shift_pattern",
            "label": "Shift pattern",
            "type": "select",
            "tier": "job",
            "value": "Day"
          }
        ]
      }
    },
    "termination": null,
    "pay_change": null,
    "probation": null,
    "includes_pay": false,
    "leave": null,
    "proposed_by": {
      "name": "Hugo Reis",
      "person_id": "p4",
      "via": "app"
    },
    "proposed_at": "2026-10-04T10:00:00.000Z",
    "steps": [
      {
        "role": "manager",
        "state": "pending",
        "fallback": false,
        "team_lead": null,
        "team_lead_blocked": null,
        "untrusted": null,
        "decided_by": null,
        "decided_at": null,
        "comment": null,
        "auto": null,
        "approvers": [
          {
            "name": "Bea Silva",
            "person_id": "p2",
            "is_viewer": true
          }
        ]
      }
    ],
    "closed_at": null,
    "closed_by": null,
    "can_decide": true,
    "can_cancel": false,
    "is_proposer": false,
    "can_reject": true
  }
}

Approve a change request#

POST/v1/org/approvals.approveWrite

Approves the step of a request that is waiting for you, with an optional comment. On the last step the change is applied exactly as org_people_change_job, org_people_terminate or org_pay_add would apply it (same checks, effective date and warnings); if it can no longer apply (for example the new manager left) approving is refused with the reason, and you can reject it instead. A request whose effective date passed is recorded backdated; 30 days after it, it expires. Only in the app, by the step's approver: the person's manager (with no manager: the team lead the request names in team_lead), or an owner, admin or HR member; never the proposer of an app request, never about yourself. Over an API key or MCP it is refused.

Web app only
Refused for API keys and connected apps. Approving needs a person signed in to Bizisy.
MCP tool
org_approvals_approve on My Workplace, 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

  • approval_idstringrequired
  • commentstring

    Up to 500 characters.

  • stepinteger

    From 0 to 5.

  • regrettedboolean | null

    HR only, for a voluntary leaving type (resignation, retirement): would you have wanted to keep this person? true, false, or null (not set). Used only in attrition reports (regretted attrition), never shown to the person or their team. Refused with another leaving type.

Returns

25 fields
  • idstringrequired
  • kind"job_change" | "termination" | "pay_change"required
  • status"pending" | "approved" | "rejected" | "cancelled" | "outdated" | "expired"required
  • personobjectrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • effective_datestringrequired
  • expires_onstringrequired
  • changestring (enum)required

    One of: change_job, terminate, pay_add, correct_job, rehire, pay_remove, leave, promote, probation, profile_title, details.

  • job_changeobject | nullrequired
    3 fields
    • reason"change" | "promotion" | "transfer" | "correction" | "rehire"required
    • beforeobject | nullrequired
      23 fields
      • idstringrequired
      • valid_fromstringrequired
      • valid_tostring | nullrequired
      • titlestringrequired

        The job title as the catalog names it now (reports and grouping use this).

      • title_idstring | nullrequired

        The catalog title (org_titles_list); null while not in the catalog yet.

      • display_titlestring | nullrequired

        A different title shown on the profile, chart and directory; null: the catalog title.

      • unitobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • managerobject | nullrequired
        4 fields
        • idstringrequired
        • namestringrequired
        • titlestring | nullrequired
        • photo_urlstring | nullrequired
      • locationobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • legal_entityobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • employment_type"full_time" | "part_time" | "contractor" | "intern"required
      • ftenumberrequired
      • reasonstringrequired
      • end_reasonstring | nullrequired
      • leaving_typestring (enum)required

        Why the employment ended (structured); null: not recorded or still employed.

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

      • toldboolean | nullrequired

        With a termination (end_reason): whether the person has been told about this last day; false: only HR and their manager know, until org_people_mark_told or the day passes. null on other rows.

      • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
      • contract_end_datestring | nullrequired
      • probation_end_datestring | nullrequired
      • weekly_hoursnumber | nullrequired
      • notice_period_daysinteger | nullrequired
      • customobject[]required

        Job custom fields (target job) on this row, effective-dated: each job row keeps its own values. Only for those who see the job details.

        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
      • regrettedboolean | null

        Private (people analytics): on the row a voluntary termination ends, whether HR marked the leaver as regretted (null: not set). Only owners, admins and HR in the app see it; absent for everyone else.

    • afterobjectrequired
      23 fields
      • idstringrequired
      • valid_fromstringrequired
      • valid_tostring | nullrequired
      • titlestringrequired

        The job title as the catalog names it now (reports and grouping use this).

      • title_idstring | nullrequired

        The catalog title (org_titles_list); null while not in the catalog yet.

      • display_titlestring | nullrequired

        A different title shown on the profile, chart and directory; null: the catalog title.

      • unitobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • managerobject | nullrequired
        4 fields
        • idstringrequired
        • namestringrequired
        • titlestring | nullrequired
        • photo_urlstring | nullrequired
      • locationobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • legal_entityobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • employment_type"full_time" | "part_time" | "contractor" | "intern"required
      • ftenumberrequired
      • reasonstringrequired
      • end_reasonstring | nullrequired
      • leaving_typestring (enum)required

        Why the employment ended (structured); null: not recorded or still employed.

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

      • toldboolean | nullrequired

        With a termination (end_reason): whether the person has been told about this last day; false: only HR and their manager know, until org_people_mark_told or the day passes. null on other rows.

      • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
      • contract_end_datestring | nullrequired
      • probation_end_datestring | nullrequired
      • weekly_hoursnumber | nullrequired
      • notice_period_daysinteger | nullrequired
      • customobject[]required

        Job custom fields (target job) on this row, effective-dated: each job row keeps its own values. Only for those who see the job details.

        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
      • regrettedboolean | null

        Private (people analytics): on the row a voluntary termination ends, whether HR marked the leaver as regretted (null: not set). Only owners, admins and HR in the app see it; absent for everyone else.

  • terminationobject | nullrequired
    6 fields
    • last_daystringrequired
    • reasonstring | nullrequired
    • leaving_typestring (enum)required

      The leaving type the request records (null: none given; a moved termination keeps its own).

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

    • person_toldboolean | nullrequired

      Whether the request says the person has been told (null: not said; the default for its leaving type applies).

    • jobobject | nullrequired
      23 fields
      • idstringrequired
      • valid_fromstringrequired
      • valid_tostring | nullrequired
      • titlestringrequired

        The job title as the catalog names it now (reports and grouping use this).

      • title_idstring | nullrequired

        The catalog title (org_titles_list); null while not in the catalog yet.

      • display_titlestring | nullrequired

        A different title shown on the profile, chart and directory; null: the catalog title.

      • unitobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • managerobject | nullrequired
        4 fields
        • idstringrequired
        • namestringrequired
        • titlestring | nullrequired
        • photo_urlstring | nullrequired
      • locationobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • legal_entityobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • employment_type"full_time" | "part_time" | "contractor" | "intern"required
      • ftenumberrequired
      • reasonstringrequired
      • end_reasonstring | nullrequired
      • leaving_typestring (enum)required

        Why the employment ended (structured); null: not recorded or still employed.

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

      • toldboolean | nullrequired

        With a termination (end_reason): whether the person has been told about this last day; false: only HR and their manager know, until org_people_mark_told or the day passes. null on other rows.

      • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
      • contract_end_datestring | nullrequired
      • probation_end_datestring | nullrequired
      • weekly_hoursnumber | nullrequired
      • notice_period_daysinteger | nullrequired
      • customobject[]required

        Job custom fields (target job) on this row, effective-dated: each job row keeps its own values. Only for those who see the job details.

        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
      • regrettedboolean | null

        Private (people analytics): on the row a voluntary termination ends, whether HR marked the leaver as regretted (null: not set). Only owners, admins and HR in the app see it; absent for everyone else.

    • change"end" | "move" | "cancel"required
  • pay_changeobject | nullrequired
    6 fields
    • amountnumberrequired
    • currencystringrequired
    • period"year" | "month" | "hour"required
    • notestring | nullrequired
    • beforeobject | nullrequired
      4 fields
      • amountnumberrequired
      • currencystringrequired
      • periodstringrequired
      • valid_fromstringrequired
    • removesbooleanrequired
  • probationobject | nullrequired
    2 fields
    • outcome"passed" | "extend"required
    • probation_end_datestringrequired
  • includes_paybooleanrequired
  • leaveobject | nullrequired
    3 fields
    • reassignobject[]required
      2 fields
      • personobjectrequired
        4 fields
        • idstringrequired
        • namestringrequired
        • titlestring | nullrequired
        • photo_urlstring | nullrequired
      • managerobject | nullrequired
        4 fields
        • idstringrequired
        • namestringrequired
        • titlestring | nullrequired
        • photo_urlstring | nullrequired
    • access"after_last_day" | "now" | "keep"required
    • replacement_positionbooleanrequired
  • proposed_byobjectrequired
    3 fields
    • namestringrequired
    • person_idstring | nullrequired
    • via"app" | "api"required
  • proposed_atstringrequired
  • stepsobject[]required
    11 fields
    • role"manager" | "hr"required
    • state"waiting" | "pending" | "approved" | "rejected"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
    • decided_byobject | nullrequired
      2 fields
      • namestringrequired
      • person_idstring | nullrequired
    • decided_atstring | nullrequired
    • commentstring | nullrequired
    • auto"proposed_by_approver" | "no_other_approver"required
    • approversobject[]required
      3 fields
      • namestringrequired
      • person_idstring | nullrequired
      • is_viewerbooleanrequired
  • closed_atstring | nullrequired
  • closed_byobject | nullrequired
    2 fields
    • namestringrequired
    • person_idstring | nullrequired
  • can_decidebooleanrequired
  • can_cancelbooleanrequired
  • is_proposerbooleanrequired
  • can_rejectbooleanrequired
  • decide_urlstringrequired

    Where to open (and, for approvers, decide) this request in Bizisy: a path on the company address (https://<slug>.bizisy.com + decide_url), for the app of this call (Manage or My workspace). Approving and rejecting happen there, never over MCP or an API key.

  • warningsstring[]required
  • next_quietobject[]required

    When the request moved to a next step: its approvers who are outside their working time now (right to disconnect), with when their email reaches them. The request is in their Approvals at once. Empty otherwise.

    3 fields
    • namestringrequired
    • deliver_atstringrequired
    • time_zonestringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/approvals.approve \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"approval_id":"apr1","comment":"Agreed in the review","step":0}'
Response
{
  "data": {
    "id": "apr1",
    "kind": "job_change",
    "status": "approved",
    "decide_url": "/manage/approvals/apr1",
    "person": {
      "id": "p1",
      "name": "Ana Ferreira",
      "title": "Engineer",
      "photo_url": null
    },
    "effective_date": "2026-11-01",
    "expires_on": "2026-12-01",
    "change": "change_job",
    "job_change": {
      "reason": "promotion",
      "before": {
        "id": "j1",
        "valid_from": "2024-01-15",
        "valid_to": null,
        "title": "Engineer",
        "title_id": "t1",
        "display_title": null,
        "unit": {
          "id": "u2",
          "name": "Engineering"
        },
        "manager": {
          "id": "p2",
          "name": "Rui Costa",
          "title": "CTO",
          "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
        },
        "location": {
          "id": "l1",
          "name": "Head office"
        },
        "legal_entity": {
          "id": "e1",
          "name": "Acme Lda"
        },
        "employment_type": "full_time",
        "fte": 1,
        "reason": "hire",
        "end_reason": null,
        "leaving_type": null,
        "told": null,
        "contract_type": "fixed_term",
        "contract_end_date": "2026-01-14",
        "probation_end_date": "2024-07-14",
        "weekly_hours": 40,
        "notice_period_days": 30,
        "custom": [
          {
            "key": "shift_pattern",
            "label": "Shift pattern",
            "type": "select",
            "tier": "job",
            "value": "Day"
          }
        ]
      },
      "after": {
        "id": "apr1:after",
        "valid_from": "2024-01-15",
        "valid_to": null,
        "title": "Senior Engineer",
        "title_id": "t1",
        "display_title": null,
        "unit": {
          "id": "u2",
          "name": "Engineering"
        },
        "manager": {
          "id": "p2",
          "name": "Rui Costa",
          "title": "CTO",
          "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
        },
        "location": {
          "id": "l1",
          "name": "Head office"
        },
        "legal_entity": {
          "id": "e1",
          "name": "Acme Lda"
        },
        "employment_type": "full_time",
        "fte": 1,
        "reason": "promotion",
        "end_reason": null,
        "leaving_type": null,
        "told": null,
        "contract_type": "fixed_term",
        "contract_end_date": "2026-01-14",
        "probation_end_date": "2024-07-14",
        "weekly_hours": 40,
        "notice_period_days": 30,
        "custom": [
          {
            "key": "shift_pattern",
            "label": "Shift pattern",
            "type": "select",
            "tier": "job",
            "value": "Day"
          }
        ]
      }
    },
    "termination": null,
    "pay_change": null,
    "probation": null,
    "includes_pay": false,
    "leave": null,
    "proposed_by": {
      "name": "Hugo Reis",
      "person_id": "p4",
      "via": "app"
    },
    "proposed_at": "2026-10-04T10:00:00.000Z",
    "steps": [
      {
        "role": "manager",
        "state": "approved",
        "fallback": false,
        "team_lead": null,
        "team_lead_blocked": null,
        "untrusted": null,
        "decided_by": {
          "name": "Bea Silva",
          "person_id": "p2"
        },
        "decided_at": "2026-10-05T09:00:00.000Z",
        "comment": null,
        "auto": null,
        "approvers": []
      }
    ],
    "closed_at": "2026-10-05T09:00:00.000Z",
    "closed_by": {
      "name": "Bea Silva",
      "person_id": "p2"
    },
    "can_decide": false,
    "can_cancel": false,
    "is_proposer": false,
    "can_reject": false,
    "warnings": [],
    "next_quiet": []
  }
}

Reject a change request#

POST/v1/org/approvals.rejectWrite

Rejects a request; comment (required) says why, for the proposer. Nothing changes on the person. In the app only, by the step's approver, or by any owner, admin or HR member (so a request waiting for a manager never holds the person up), never about yourself.

Web app only
Refused for API keys and connected apps. Rejecting needs a person signed in to Bizisy.
MCP tool
org_approvals_reject on My Workplace, 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

  • approval_idstringrequired
  • commentanyrequired
  • stepinteger

    From 0 to 5.

Returns

23 fields
  • idstringrequired
  • kind"job_change" | "termination" | "pay_change"required
  • status"pending" | "approved" | "rejected" | "cancelled" | "outdated" | "expired"required
  • personobjectrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • effective_datestringrequired
  • expires_onstringrequired
  • changestring (enum)required

    One of: change_job, terminate, pay_add, correct_job, rehire, pay_remove, leave, promote, probation, profile_title, details.

  • job_changeobject | nullrequired
    3 fields
    • reason"change" | "promotion" | "transfer" | "correction" | "rehire"required
    • beforeobject | nullrequired
      23 fields
      • idstringrequired
      • valid_fromstringrequired
      • valid_tostring | nullrequired
      • titlestringrequired

        The job title as the catalog names it now (reports and grouping use this).

      • title_idstring | nullrequired

        The catalog title (org_titles_list); null while not in the catalog yet.

      • display_titlestring | nullrequired

        A different title shown on the profile, chart and directory; null: the catalog title.

      • unitobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • managerobject | nullrequired
        4 fields
        • idstringrequired
        • namestringrequired
        • titlestring | nullrequired
        • photo_urlstring | nullrequired
      • locationobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • legal_entityobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • employment_type"full_time" | "part_time" | "contractor" | "intern"required
      • ftenumberrequired
      • reasonstringrequired
      • end_reasonstring | nullrequired
      • leaving_typestring (enum)required

        Why the employment ended (structured); null: not recorded or still employed.

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

      • toldboolean | nullrequired

        With a termination (end_reason): whether the person has been told about this last day; false: only HR and their manager know, until org_people_mark_told or the day passes. null on other rows.

      • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
      • contract_end_datestring | nullrequired
      • probation_end_datestring | nullrequired
      • weekly_hoursnumber | nullrequired
      • notice_period_daysinteger | nullrequired
      • customobject[]required

        Job custom fields (target job) on this row, effective-dated: each job row keeps its own values. Only for those who see the job details.

        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
      • regrettedboolean | null

        Private (people analytics): on the row a voluntary termination ends, whether HR marked the leaver as regretted (null: not set). Only owners, admins and HR in the app see it; absent for everyone else.

    • afterobjectrequired
      23 fields
      • idstringrequired
      • valid_fromstringrequired
      • valid_tostring | nullrequired
      • titlestringrequired

        The job title as the catalog names it now (reports and grouping use this).

      • title_idstring | nullrequired

        The catalog title (org_titles_list); null while not in the catalog yet.

      • display_titlestring | nullrequired

        A different title shown on the profile, chart and directory; null: the catalog title.

      • unitobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • managerobject | nullrequired
        4 fields
        • idstringrequired
        • namestringrequired
        • titlestring | nullrequired
        • photo_urlstring | nullrequired
      • locationobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • legal_entityobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • employment_type"full_time" | "part_time" | "contractor" | "intern"required
      • ftenumberrequired
      • reasonstringrequired
      • end_reasonstring | nullrequired
      • leaving_typestring (enum)required

        Why the employment ended (structured); null: not recorded or still employed.

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

      • toldboolean | nullrequired

        With a termination (end_reason): whether the person has been told about this last day; false: only HR and their manager know, until org_people_mark_told or the day passes. null on other rows.

      • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
      • contract_end_datestring | nullrequired
      • probation_end_datestring | nullrequired
      • weekly_hoursnumber | nullrequired
      • notice_period_daysinteger | nullrequired
      • customobject[]required

        Job custom fields (target job) on this row, effective-dated: each job row keeps its own values. Only for those who see the job details.

        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
      • regrettedboolean | null

        Private (people analytics): on the row a voluntary termination ends, whether HR marked the leaver as regretted (null: not set). Only owners, admins and HR in the app see it; absent for everyone else.

  • terminationobject | nullrequired
    6 fields
    • last_daystringrequired
    • reasonstring | nullrequired
    • leaving_typestring (enum)required

      The leaving type the request records (null: none given; a moved termination keeps its own).

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

    • person_toldboolean | nullrequired

      Whether the request says the person has been told (null: not said; the default for its leaving type applies).

    • jobobject | nullrequired
      23 fields
      • idstringrequired
      • valid_fromstringrequired
      • valid_tostring | nullrequired
      • titlestringrequired

        The job title as the catalog names it now (reports and grouping use this).

      • title_idstring | nullrequired

        The catalog title (org_titles_list); null while not in the catalog yet.

      • display_titlestring | nullrequired

        A different title shown on the profile, chart and directory; null: the catalog title.

      • unitobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • managerobject | nullrequired
        4 fields
        • idstringrequired
        • namestringrequired
        • titlestring | nullrequired
        • photo_urlstring | nullrequired
      • locationobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • legal_entityobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • employment_type"full_time" | "part_time" | "contractor" | "intern"required
      • ftenumberrequired
      • reasonstringrequired
      • end_reasonstring | nullrequired
      • leaving_typestring (enum)required

        Why the employment ended (structured); null: not recorded or still employed.

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

      • toldboolean | nullrequired

        With a termination (end_reason): whether the person has been told about this last day; false: only HR and their manager know, until org_people_mark_told or the day passes. null on other rows.

      • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
      • contract_end_datestring | nullrequired
      • probation_end_datestring | nullrequired
      • weekly_hoursnumber | nullrequired
      • notice_period_daysinteger | nullrequired
      • customobject[]required

        Job custom fields (target job) on this row, effective-dated: each job row keeps its own values. Only for those who see the job details.

        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
      • regrettedboolean | null

        Private (people analytics): on the row a voluntary termination ends, whether HR marked the leaver as regretted (null: not set). Only owners, admins and HR in the app see it; absent for everyone else.

    • change"end" | "move" | "cancel"required
  • pay_changeobject | nullrequired
    6 fields
    • amountnumberrequired
    • currencystringrequired
    • period"year" | "month" | "hour"required
    • notestring | nullrequired
    • beforeobject | nullrequired
      4 fields
      • amountnumberrequired
      • currencystringrequired
      • periodstringrequired
      • valid_fromstringrequired
    • removesbooleanrequired
  • probationobject | nullrequired
    2 fields
    • outcome"passed" | "extend"required
    • probation_end_datestringrequired
  • includes_paybooleanrequired
  • leaveobject | nullrequired
    3 fields
    • reassignobject[]required
      2 fields
      • personobjectrequired
        4 fields
        • idstringrequired
        • namestringrequired
        • titlestring | nullrequired
        • photo_urlstring | nullrequired
      • managerobject | nullrequired
        4 fields
        • idstringrequired
        • namestringrequired
        • titlestring | nullrequired
        • photo_urlstring | nullrequired
    • access"after_last_day" | "now" | "keep"required
    • replacement_positionbooleanrequired
  • proposed_byobjectrequired
    3 fields
    • namestringrequired
    • person_idstring | nullrequired
    • via"app" | "api"required
  • proposed_atstringrequired
  • stepsobject[]required
    11 fields
    • role"manager" | "hr"required
    • state"waiting" | "pending" | "approved" | "rejected"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
    • decided_byobject | nullrequired
      2 fields
      • namestringrequired
      • person_idstring | nullrequired
    • decided_atstring | nullrequired
    • commentstring | nullrequired
    • auto"proposed_by_approver" | "no_other_approver"required
    • approversobject[]required
      3 fields
      • namestringrequired
      • person_idstring | nullrequired
      • is_viewerbooleanrequired
  • closed_atstring | nullrequired
  • closed_byobject | nullrequired
    2 fields
    • namestringrequired
    • person_idstring | nullrequired
  • can_decidebooleanrequired
  • can_cancelbooleanrequired
  • is_proposerbooleanrequired
  • can_rejectbooleanrequired
  • decide_urlstringrequired

    Where to open (and, for approvers, decide) this request in Bizisy: a path on the company address (https://<slug>.bizisy.com + decide_url), for the app of this call (Manage or My workspace). Approving and rejecting happen there, never over MCP or an API key.

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/approvals.reject \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"approval_id":"apr1","comment":"Wait for the budget","step":0}'
Response
{
  "data": {
    "id": "apr1",
    "kind": "job_change",
    "status": "rejected",
    "decide_url": "/manage/approvals/apr1",
    "person": {
      "id": "p1",
      "name": "Ana Ferreira",
      "title": "Engineer",
      "photo_url": null
    },
    "effective_date": "2026-11-01",
    "expires_on": "2026-12-01",
    "change": "change_job",
    "job_change": {
      "reason": "promotion",
      "before": {
        "id": "j1",
        "valid_from": "2024-01-15",
        "valid_to": null,
        "title": "Engineer",
        "title_id": "t1",
        "display_title": null,
        "unit": {
          "id": "u2",
          "name": "Engineering"
        },
        "manager": {
          "id": "p2",
          "name": "Rui Costa",
          "title": "CTO",
          "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
        },
        "location": {
          "id": "l1",
          "name": "Head office"
        },
        "legal_entity": {
          "id": "e1",
          "name": "Acme Lda"
        },
        "employment_type": "full_time",
        "fte": 1,
        "reason": "hire",
        "end_reason": null,
        "leaving_type": null,
        "told": null,
        "contract_type": "fixed_term",
        "contract_end_date": "2026-01-14",
        "probation_end_date": "2024-07-14",
        "weekly_hours": 40,
        "notice_period_days": 30,
        "custom": [
          {
            "key": "shift_pattern",
            "label": "Shift pattern",
            "type": "select",
            "tier": "job",
            "value": "Day"
          }
        ]
      },
      "after": {
        "id": "apr1:after",
        "valid_from": "2024-01-15",
        "valid_to": null,
        "title": "Senior Engineer",
        "title_id": "t1",
        "display_title": null,
        "unit": {
          "id": "u2",
          "name": "Engineering"
        },
        "manager": {
          "id": "p2",
          "name": "Rui Costa",
          "title": "CTO",
          "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
        },
        "location": {
          "id": "l1",
          "name": "Head office"
        },
        "legal_entity": {
          "id": "e1",
          "name": "Acme Lda"
        },
        "employment_type": "full_time",
        "fte": 1,
        "reason": "promotion",
        "end_reason": null,
        "leaving_type": null,
        "told": null,
        "contract_type": "fixed_term",
        "contract_end_date": "2026-01-14",
        "probation_end_date": "2024-07-14",
        "weekly_hours": 40,
        "notice_period_days": 30,
        "custom": [
          {
            "key": "shift_pattern",
            "label": "Shift pattern",
            "type": "select",
            "tier": "job",
            "value": "Day"
          }
        ]
      }
    },
    "termination": null,
    "pay_change": null,
    "probation": null,
    "includes_pay": false,
    "leave": null,
    "proposed_by": {
      "name": "Hugo Reis",
      "person_id": "p4",
      "via": "app"
    },
    "proposed_at": "2026-10-04T10:00:00.000Z",
    "steps": [
      {
        "role": "manager",
        "state": "rejected",
        "fallback": false,
        "team_lead": null,
        "team_lead_blocked": null,
        "untrusted": null,
        "decided_by": {
          "name": "Bea Silva",
          "person_id": "p2"
        },
        "decided_at": "2026-10-05T09:00:00.000Z",
        "comment": "Wait for the budget",
        "auto": null,
        "approvers": []
      }
    ],
    "closed_at": "2026-10-05T09:00:00.000Z",
    "closed_by": {
      "name": "Bea Silva",
      "person_id": "p2"
    },
    "can_decide": false,
    "can_cancel": false,
    "is_proposer": false,
    "can_reject": false
  }
}

Withdraw a change request#

POST/v1/org/approvals.cancelWrite

Withdraws a request that is waiting (or expired): nothing changes on the person. The proposer, or an owner, admin or HR member who can see it. Works over an API key for job and termination requests.

Who can call it
Manage key owner admin hr
MCP tool
org_approvals_cancel 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

  • approval_idstringrequired

Returns

23 fields
  • idstringrequired
  • kind"job_change" | "termination" | "pay_change"required
  • status"pending" | "approved" | "rejected" | "cancelled" | "outdated" | "expired"required
  • personobjectrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • effective_datestringrequired
  • expires_onstringrequired
  • changestring (enum)required

    One of: change_job, terminate, pay_add, correct_job, rehire, pay_remove, leave, promote, probation, profile_title, details.

  • job_changeobject | nullrequired
    3 fields
    • reason"change" | "promotion" | "transfer" | "correction" | "rehire"required
    • beforeobject | nullrequired
      23 fields
      • idstringrequired
      • valid_fromstringrequired
      • valid_tostring | nullrequired
      • titlestringrequired

        The job title as the catalog names it now (reports and grouping use this).

      • title_idstring | nullrequired

        The catalog title (org_titles_list); null while not in the catalog yet.

      • display_titlestring | nullrequired

        A different title shown on the profile, chart and directory; null: the catalog title.

      • unitobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • managerobject | nullrequired
        4 fields
        • idstringrequired
        • namestringrequired
        • titlestring | nullrequired
        • photo_urlstring | nullrequired
      • locationobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • legal_entityobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • employment_type"full_time" | "part_time" | "contractor" | "intern"required
      • ftenumberrequired
      • reasonstringrequired
      • end_reasonstring | nullrequired
      • leaving_typestring (enum)required

        Why the employment ended (structured); null: not recorded or still employed.

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

      • toldboolean | nullrequired

        With a termination (end_reason): whether the person has been told about this last day; false: only HR and their manager know, until org_people_mark_told or the day passes. null on other rows.

      • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
      • contract_end_datestring | nullrequired
      • probation_end_datestring | nullrequired
      • weekly_hoursnumber | nullrequired
      • notice_period_daysinteger | nullrequired
      • customobject[]required

        Job custom fields (target job) on this row, effective-dated: each job row keeps its own values. Only for those who see the job details.

        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
      • regrettedboolean | null

        Private (people analytics): on the row a voluntary termination ends, whether HR marked the leaver as regretted (null: not set). Only owners, admins and HR in the app see it; absent for everyone else.

    • afterobjectrequired
      23 fields
      • idstringrequired
      • valid_fromstringrequired
      • valid_tostring | nullrequired
      • titlestringrequired

        The job title as the catalog names it now (reports and grouping use this).

      • title_idstring | nullrequired

        The catalog title (org_titles_list); null while not in the catalog yet.

      • display_titlestring | nullrequired

        A different title shown on the profile, chart and directory; null: the catalog title.

      • unitobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • managerobject | nullrequired
        4 fields
        • idstringrequired
        • namestringrequired
        • titlestring | nullrequired
        • photo_urlstring | nullrequired
      • locationobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • legal_entityobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • employment_type"full_time" | "part_time" | "contractor" | "intern"required
      • ftenumberrequired
      • reasonstringrequired
      • end_reasonstring | nullrequired
      • leaving_typestring (enum)required

        Why the employment ended (structured); null: not recorded or still employed.

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

      • toldboolean | nullrequired

        With a termination (end_reason): whether the person has been told about this last day; false: only HR and their manager know, until org_people_mark_told or the day passes. null on other rows.

      • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
      • contract_end_datestring | nullrequired
      • probation_end_datestring | nullrequired
      • weekly_hoursnumber | nullrequired
      • notice_period_daysinteger | nullrequired
      • customobject[]required

        Job custom fields (target job) on this row, effective-dated: each job row keeps its own values. Only for those who see the job details.

        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
      • regrettedboolean | null

        Private (people analytics): on the row a voluntary termination ends, whether HR marked the leaver as regretted (null: not set). Only owners, admins and HR in the app see it; absent for everyone else.

  • terminationobject | nullrequired
    6 fields
    • last_daystringrequired
    • reasonstring | nullrequired
    • leaving_typestring (enum)required

      The leaving type the request records (null: none given; a moved termination keeps its own).

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

    • person_toldboolean | nullrequired

      Whether the request says the person has been told (null: not said; the default for its leaving type applies).

    • jobobject | nullrequired
      23 fields
      • idstringrequired
      • valid_fromstringrequired
      • valid_tostring | nullrequired
      • titlestringrequired

        The job title as the catalog names it now (reports and grouping use this).

      • title_idstring | nullrequired

        The catalog title (org_titles_list); null while not in the catalog yet.

      • display_titlestring | nullrequired

        A different title shown on the profile, chart and directory; null: the catalog title.

      • unitobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • managerobject | nullrequired
        4 fields
        • idstringrequired
        • namestringrequired
        • titlestring | nullrequired
        • photo_urlstring | nullrequired
      • locationobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • legal_entityobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • employment_type"full_time" | "part_time" | "contractor" | "intern"required
      • ftenumberrequired
      • reasonstringrequired
      • end_reasonstring | nullrequired
      • leaving_typestring (enum)required

        Why the employment ended (structured); null: not recorded or still employed.

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

      • toldboolean | nullrequired

        With a termination (end_reason): whether the person has been told about this last day; false: only HR and their manager know, until org_people_mark_told or the day passes. null on other rows.

      • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
      • contract_end_datestring | nullrequired
      • probation_end_datestring | nullrequired
      • weekly_hoursnumber | nullrequired
      • notice_period_daysinteger | nullrequired
      • customobject[]required

        Job custom fields (target job) on this row, effective-dated: each job row keeps its own values. Only for those who see the job details.

        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
      • regrettedboolean | null

        Private (people analytics): on the row a voluntary termination ends, whether HR marked the leaver as regretted (null: not set). Only owners, admins and HR in the app see it; absent for everyone else.

    • change"end" | "move" | "cancel"required
  • pay_changeobject | nullrequired
    6 fields
    • amountnumberrequired
    • currencystringrequired
    • period"year" | "month" | "hour"required
    • notestring | nullrequired
    • beforeobject | nullrequired
      4 fields
      • amountnumberrequired
      • currencystringrequired
      • periodstringrequired
      • valid_fromstringrequired
    • removesbooleanrequired
  • probationobject | nullrequired
    2 fields
    • outcome"passed" | "extend"required
    • probation_end_datestringrequired
  • includes_paybooleanrequired
  • leaveobject | nullrequired
    3 fields
    • reassignobject[]required
      2 fields
      • personobjectrequired
        4 fields
        • idstringrequired
        • namestringrequired
        • titlestring | nullrequired
        • photo_urlstring | nullrequired
      • managerobject | nullrequired
        4 fields
        • idstringrequired
        • namestringrequired
        • titlestring | nullrequired
        • photo_urlstring | nullrequired
    • access"after_last_day" | "now" | "keep"required
    • replacement_positionbooleanrequired
  • proposed_byobjectrequired
    3 fields
    • namestringrequired
    • person_idstring | nullrequired
    • via"app" | "api"required
  • proposed_atstringrequired
  • stepsobject[]required
    11 fields
    • role"manager" | "hr"required
    • state"waiting" | "pending" | "approved" | "rejected"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
    • decided_byobject | nullrequired
      2 fields
      • namestringrequired
      • person_idstring | nullrequired
    • decided_atstring | nullrequired
    • commentstring | nullrequired
    • auto"proposed_by_approver" | "no_other_approver"required
    • approversobject[]required
      3 fields
      • namestringrequired
      • person_idstring | nullrequired
      • is_viewerbooleanrequired
  • closed_atstring | nullrequired
  • closed_byobject | nullrequired
    2 fields
    • namestringrequired
    • person_idstring | nullrequired
  • can_decidebooleanrequired
  • can_cancelbooleanrequired
  • is_proposerbooleanrequired
  • can_rejectbooleanrequired
  • decide_urlstringrequired

    Where to open (and, for approvers, decide) this request in Bizisy: a path on the company address (https://<slug>.bizisy.com + decide_url), for the app of this call (Manage or My workspace). Approving and rejecting happen there, never over MCP or an API key.

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/approvals.cancel \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"approval_id":"apr1"}'
Response
{
  "data": {
    "id": "apr1",
    "kind": "job_change",
    "status": "cancelled",
    "decide_url": "/manage/approvals/apr1",
    "person": {
      "id": "p1",
      "name": "Ana Ferreira",
      "title": "Engineer",
      "photo_url": null
    },
    "effective_date": "2026-11-01",
    "expires_on": "2026-12-01",
    "change": "change_job",
    "job_change": {
      "reason": "promotion",
      "before": {
        "id": "j1",
        "valid_from": "2024-01-15",
        "valid_to": null,
        "title": "Engineer",
        "title_id": "t1",
        "display_title": null,
        "unit": {
          "id": "u2",
          "name": "Engineering"
        },
        "manager": {
          "id": "p2",
          "name": "Rui Costa",
          "title": "CTO",
          "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
        },
        "location": {
          "id": "l1",
          "name": "Head office"
        },
        "legal_entity": {
          "id": "e1",
          "name": "Acme Lda"
        },
        "employment_type": "full_time",
        "fte": 1,
        "reason": "hire",
        "end_reason": null,
        "leaving_type": null,
        "told": null,
        "contract_type": "fixed_term",
        "contract_end_date": "2026-01-14",
        "probation_end_date": "2024-07-14",
        "weekly_hours": 40,
        "notice_period_days": 30,
        "custom": [
          {
            "key": "shift_pattern",
            "label": "Shift pattern",
            "type": "select",
            "tier": "job",
            "value": "Day"
          }
        ]
      },
      "after": {
        "id": "apr1:after",
        "valid_from": "2024-01-15",
        "valid_to": null,
        "title": "Senior Engineer",
        "title_id": "t1",
        "display_title": null,
        "unit": {
          "id": "u2",
          "name": "Engineering"
        },
        "manager": {
          "id": "p2",
          "name": "Rui Costa",
          "title": "CTO",
          "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
        },
        "location": {
          "id": "l1",
          "name": "Head office"
        },
        "legal_entity": {
          "id": "e1",
          "name": "Acme Lda"
        },
        "employment_type": "full_time",
        "fte": 1,
        "reason": "promotion",
        "end_reason": null,
        "leaving_type": null,
        "told": null,
        "contract_type": "fixed_term",
        "contract_end_date": "2026-01-14",
        "probation_end_date": "2024-07-14",
        "weekly_hours": 40,
        "notice_period_days": 30,
        "custom": [
          {
            "key": "shift_pattern",
            "label": "Shift pattern",
            "type": "select",
            "tier": "job",
            "value": "Day"
          }
        ]
      }
    },
    "termination": null,
    "pay_change": null,
    "probation": null,
    "includes_pay": false,
    "leave": null,
    "proposed_by": {
      "name": "Hugo Reis",
      "person_id": "p4",
      "via": "app"
    },
    "proposed_at": "2026-10-04T10:00:00.000Z",
    "steps": [
      {
        "role": "manager",
        "state": "pending",
        "fallback": false,
        "team_lead": null,
        "team_lead_blocked": null,
        "untrusted": null,
        "decided_by": null,
        "decided_at": null,
        "comment": null,
        "auto": null,
        "approvers": []
      }
    ],
    "closed_at": "2026-10-05T09:00:00.000Z",
    "closed_by": {
      "name": "Hugo Reis",
      "person_id": "p4"
    },
    "can_decide": false,
    "can_cancel": false,
    "is_proposer": false,
    "can_reject": false
  }
}

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

Developer docs