Skip to content

API reference

People

The directory, finding anything by name, queries over people, one person's profile, profile changes and photos, and bank account changes with a proof (Verified bank details).

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

List people (directory)#

POST/v1/org/people.listRead

Lists people as of a date (default: today in the company time zone), sorted by name. Returns public fields only (use org_people_get for one person). Filters combine (AND): status defaults to active + pre_hire ("terminated" or "all" include leavers; when joined_between or left_between is set it defaults to all); q searches name, email and title (case-insensitive); unit_id (ids from org_units_list; include_subunits=true adds every unit below it); location_id (org_locations_list); manager_id (a person id: their direct reports). HR filters (owners, admins and HR, in the app only; forbidden for others and over MCP or an API key, since they reveal job details): legal_entity_id (org_entities_list); joined_between {from, to} (YYYY-MM-DD, inclusive: an employment period, hire or rehire, starts in the range) and left_between {from, to} (the last day of an employment period falls in the range, including scheduled ones), counted as org_reports_headcount counts joiners and leavers. Unit, location, entity and manager are those of the job shown for the person as of the date (for leavers, their last job). A scheduled last day is job detail: with a future as_of, people whose job you cannot see still show as employed if they are today. Unknown ids are not_found. Erased people are never listed. group_id: only members of a saved group (org_groups_list), today and as you see them (a condition on data you may not see for someone is not met for them); for owners, admins, HR, viewers and custom roles that are not outsiders.

Who can call it
Manage key any Manage role
Me key anyone
Keys and apps
The HR filters legal_entity_id, joined_between and left_between are refused.
MCP tool
org_people_list on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • as_ofstring
  • status"active" | "pre_hire" | "terminated" | "invited" | "all"

    invited: people invited by email who are still waiting for their details (owners, admins and HR, and roles that cover them).

  • qstring

    Up to 100 characters.

  • unit_idstring
  • include_subunitsboolean
  • location_idstring
  • legal_entity_idstring
  • manager_idstring
  • joined_betweenobject
    2 fields
    • fromstringrequired
    • tostringrequired
  • left_betweenobject
    2 fields
    • fromstringrequired
    • tostringrequired
  • group_idstring

Returns

An array of objects with 15 fields

An array of objects:

  • idstringrequired
  • namestringrequired
  • given_namestringrequired
  • family_namestringrequired
  • preferred_namestring | nullrequired
  • work_emailstringrequired
  • titlestring | nullrequired
  • status"invited" | "pre_hire" | "active" | "terminated" | "none"required

    invited: waiting for their details (names, title, start date), not employed yet; pre_hire: starts later; active; terminated: has left; none: no job.

  • start_datestring | nullrequired
  • unitobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • locationobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • managerobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • invitedbooleanrequired
  • has_loginbooleanrequired
  • photo_urlstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/people.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "joined_between": {
    "from": "2026-03-01",
    "to": "2026-03-31"
  },
  "left_between": {
    "from": "2026-01-01",
    "to": "2026-12-31"
  }
}'
Response
{
  "data": [
    {
      "id": "p1",
      "name": "Ana Ferreira",
      "given_name": "Ana",
      "family_name": "Ferreira",
      "preferred_name": null,
      "work_email": "ana@acme.test",
      "title": "Engineer",
      "status": "active",
      "start_date": "2024-01-15",
      "unit": {
        "id": "u2",
        "name": "Engineering"
      },
      "location": {
        "id": "l1",
        "name": "Head office"
      },
      "manager": {
        "id": "p2",
        "name": "Rui Costa",
        "title": "CTO",
        "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
      },
      "invited": true,
      "has_login": true,
      "photo_url": null
    },
    {
      "id": "p3",
      "name": "Ana Ferreira",
      "given_name": "Ana",
      "family_name": "Ferreira",
      "preferred_name": null,
      "work_email": "ana@acme.test",
      "title": "Engineer",
      "status": "pre_hire",
      "start_date": "2024-01-15",
      "unit": null,
      "location": null,
      "manager": null,
      "invited": true,
      "has_login": true,
      "photo_url": null
    }
  ]
}

Get a person#

POST/v1/org/people.getRead

Returns one person as of a date: profile, current job, manager, direct reports and job history. Fields you may not see come back null; visible_tiers says which tiers (public, private, job, pay) you got; custom lists the custom fields you may see. Over MCP or an API key, private fields are only returned for yourself. Pay is separate: org_pay_list.

Who can call it
Manage key any Manage role
Me key anyone
Keys and apps
Private fields only for yourself.
MCP tool
org_people_get on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • person_idstringrequired
  • as_ofstring

Returns

35 fields
  • idstringrequired
  • namestringrequired
  • given_namestringrequired
  • family_namestringrequired
  • preferred_namestring | nullrequired
  • work_emailstringrequired
  • titlestring | nullrequired
  • status"invited" | "pre_hire" | "active" | "terminated" | "none"required

    invited: waiting for their details (names, title, start date), not employed yet; pre_hire: starts later; active; terminated: has left; none: no job.

  • start_datestring | nullrequired
  • unitobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • locationobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • managerobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • invitedbooleanrequired
  • has_loginbooleanrequired
  • photo_urlstring | nullrequired
  • pronounsstring | nullrequired
  • work_phonestring | nullrequired
  • personal_emailstring | nullrequired
  • personal_phonestring | nullrequired
  • addressobject | nullrequired
    5 fields
    • line1stringrequired
    • line2string
    • citystringrequired
    • postal_codestring
    • countrystringrequired
  • birthdaystring | nullrequired
  • sex"female" | "male" | "another" | "undisclosed"required

    For equal-pay reporting only (private: the person, owners, admins and HR in the app). female and male are compared; another and undisclosed are counted, not compared.

  • emergency_contactsobject[] | nullrequired
    3 fields
    • namestringrequired
    • relationshipstringrequired
    • phonestringrequired
  • tax_idstring | nullrequired
  • social_security_numberstring | nullrequired
  • ibanstring | nullrequired
  • customobject[]required
    7 fields
    • keystringrequired
    • labelstringrequired
    • typestring (enum)required

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

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

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

    • fileobject | null

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

      4 fields
      • namestring | nullrequired

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

      • sizeintegerrequired
      • content_typestringrequired
      • previewablebooleanrequired

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

    • personobject | null

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

      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
  • 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.

  • historyobject[] | 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.

  • reportsobject[]required
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • visible_tiers"public" | "private" | "job" | "pay"[]required
  • plannedobject | nullrequired

    While invited (status invited): the job details known so far (job tier; null otherwise or when not visible).

    14 fields
    • titlestring | nullrequired
    • title_idstring | nullrequired
    • start_datestring | nullrequired
    • 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
    • ftenumber | nullrequired
    • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
    • contract_end_datestring | nullrequired
    • probation_end_datestring | nullrequired
    • weekly_hoursnumber | nullrequired
    • notice_period_daysinteger | nullrequired
  • missing"given_name" | "family_name" | "title" | "start_date"[]required

    While invited: what is still needed to register them (given_name, family_name, title, start_date); [] otherwise.

  • dotted_managersobject[]required

    Dotted-line managers today (spec structure-over-time D10): they see job details, never approve.

    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • dotted_reportsobject[]required

    People this person has a dotted line to today.

    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/people.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"person_id":"p1","as_of":"2026-10-04"}'
Response
{
  "data": {
    "id": "p1",
    "name": "Ana Ferreira",
    "given_name": "Ana",
    "family_name": "Ferreira",
    "preferred_name": null,
    "work_email": "ana@acme.test",
    "title": "Engineer",
    "status": "active",
    "start_date": "2024-01-15",
    "unit": {
      "id": "u2",
      "name": "Engineering"
    },
    "location": {
      "id": "l1",
      "name": "Head office"
    },
    "manager": {
      "id": "p2",
      "name": "Rui Costa",
      "title": "CTO",
      "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
    },
    "invited": true,
    "has_login": true,
    "photo_url": null,
    "pronouns": "she/her",
    "work_phone": "+351 210 000 000",
    "personal_email": null,
    "personal_phone": null,
    "address": null,
    "birthday": null,
    "sex": "female",
    "emergency_contacts": null,
    "tax_id": null,
    "social_security_number": null,
    "iban": null,
    "custom": [
      {
        "key": "t_shirt_size",
        "label": "T-shirt size",
        "type": "select",
        "tier": "public",
        "value": "M"
      },
      {
        "key": "remote",
        "label": "Remote allowance",
        "type": "boolean",
        "tier": "job",
        "value": null
      }
    ],
    "job": {
      "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"
        }
      ]
    },
    "history": [
      {
        "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"
          }
        ]
      }
    ],
    "reports": [],
    "visible_tiers": [
      "public",
      "job"
    ],
    "planned": null,
    "missing": [],
    "dotted_managers": [
      {
        "id": "p7",
        "name": "João Pereira",
        "title": "Sales Lead",
        "photo_url": null
      }
    ],
    "dotted_reports": []
  }
}

Update a person's profile#

POST/v1/org/people.update_profileWrite

Changes profile fields of a person (names, work email, phones, personal email, address, birthday, pronouns, emergency contacts, sex (female, male, another or undisclosed: for equal-pay reporting only, private, never written over MCP or an API key), tax_id, social_security_number, iban: payroll details change only in the app, never over MCP or an API key, and the person and every owner, admin and HR member are emailed when they change) and custom field values (custom: { <key>: value or null }, keys from org_fields_list). Send only the fields to change; null clears a field. Only owners and admins can change the work email of an owner's or admin's login. Job changes go through org_people_change_job.

Who can call it
Manage key owner admin hr
Keys and apps
Payroll details (tax_id, social_security_number, iban) and sex are refused.
MCP tool
org_people_update_profile 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

  • given_namestring

    1–100 characters.

  • family_namestring

    1–100 characters.

  • work_emailany
  • preferred_namestring | null

    1–100 characters.

  • pronounsstring | null

    Up to 40 characters.

  • work_phonestring | null

    Pattern ^\+?[0-9 ().-]{3,40}$.

  • personal_emailany | null
  • personal_phonestring | null

    Pattern ^\+?[0-9 ().-]{3,40}$.

  • addressobject | null
    5 fields
    • line1stringrequired

      1–200 characters.

    • line2string

      Up to 200 characters.

    • citystringrequired

      1–100 characters.

    • postal_codestring

      Up to 20 characters.

    • countryanyrequired
  • birthdaystring | null
  • sex"female" | "male" | "another" | "undisclosed"

    Sex for equal-pay reporting (EU Pay Transparency Directive): female, male, another or undisclosed. Private; used in pay gap totals only.

  • emergency_contactsobject[]

    Up to 5 items.

    3 fields
    • namestringrequired

      1–100 characters.

    • relationshipstringrequired

      1–60 characters.

    • phonestringrequired

      Pattern ^\+?[0-9 ().-]{3,40}$.

  • tax_idstring | null

    Pattern ^[A-Za-z0-9 ./-]{1,40}$.

  • social_security_numberstring | null

    Pattern ^[A-Za-z0-9 ./-]{1,40}$.

  • ibanany | null
  • customobject

    Custom field values by key (org_fields_list); null (or [] for a table) clears one. Person fields take a person id; table fields take rows [{ <column key>: value }].

  • person_idstringrequired

Returns

35 fields
  • idstringrequired
  • namestringrequired
  • given_namestringrequired
  • family_namestringrequired
  • preferred_namestring | nullrequired
  • work_emailstringrequired
  • titlestring | nullrequired
  • status"invited" | "pre_hire" | "active" | "terminated" | "none"required

    invited: waiting for their details (names, title, start date), not employed yet; pre_hire: starts later; active; terminated: has left; none: no job.

  • start_datestring | nullrequired
  • unitobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • locationobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • managerobject | nullrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • invitedbooleanrequired
  • has_loginbooleanrequired
  • photo_urlstring | nullrequired
  • pronounsstring | nullrequired
  • work_phonestring | nullrequired
  • personal_emailstring | nullrequired
  • personal_phonestring | nullrequired
  • addressobject | nullrequired
    5 fields
    • line1stringrequired
    • line2string
    • citystringrequired
    • postal_codestring
    • countrystringrequired
  • birthdaystring | nullrequired
  • sex"female" | "male" | "another" | "undisclosed"required

    For equal-pay reporting only (private: the person, owners, admins and HR in the app). female and male are compared; another and undisclosed are counted, not compared.

  • emergency_contactsobject[] | nullrequired
    3 fields
    • namestringrequired
    • relationshipstringrequired
    • phonestringrequired
  • tax_idstring | nullrequired
  • social_security_numberstring | nullrequired
  • ibanstring | nullrequired
  • customobject[]required
    7 fields
    • keystringrequired
    • labelstringrequired
    • typestring (enum)required

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

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

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

    • fileobject | null

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

      4 fields
      • namestring | nullrequired

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

      • sizeintegerrequired
      • content_typestringrequired
      • previewablebooleanrequired

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

    • personobject | null

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

      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
  • 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.

  • historyobject[] | 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.

  • reportsobject[]required
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • visible_tiers"public" | "private" | "job" | "pay"[]required
  • plannedobject | nullrequired

    While invited (status invited): the job details known so far (job tier; null otherwise or when not visible).

    14 fields
    • titlestring | nullrequired
    • title_idstring | nullrequired
    • start_datestring | nullrequired
    • 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
    • ftenumber | nullrequired
    • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
    • contract_end_datestring | nullrequired
    • probation_end_datestring | nullrequired
    • weekly_hoursnumber | nullrequired
    • notice_period_daysinteger | nullrequired
  • missing"given_name" | "family_name" | "title" | "start_date"[]required

    While invited: what is still needed to register them (given_name, family_name, title, start_date); [] otherwise.

  • dotted_managersobject[]required

    Dotted-line managers today (spec structure-over-time D10): they see job details, never approve.

    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • dotted_reportsobject[]required

    People this person has a dotted line to today.

    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/people.update_profile \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "person_id": "p1",
  "given_name": "Ana Maria",
  "work_email": "ana.maria@acme.test",
  "address": null,
  "emergency_contacts": [],
  "sex": "female"
}'
Response
{
  "data": {
    "id": "p1",
    "name": "Ana Maria Ferreira",
    "given_name": "Ana Maria",
    "family_name": "Ferreira",
    "preferred_name": null,
    "work_email": "ana.maria@acme.test",
    "title": "Engineer",
    "status": "active",
    "start_date": "2024-01-15",
    "unit": {
      "id": "u2",
      "name": "Engineering"
    },
    "location": {
      "id": "l1",
      "name": "Head office"
    },
    "manager": {
      "id": "p2",
      "name": "Rui Costa",
      "title": "CTO",
      "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
    },
    "invited": true,
    "has_login": true,
    "photo_url": null,
    "pronouns": "she/her",
    "work_phone": "+351 210 000 000",
    "personal_email": null,
    "personal_phone": null,
    "address": null,
    "birthday": null,
    "sex": "female",
    "emergency_contacts": null,
    "tax_id": null,
    "social_security_number": null,
    "iban": null,
    "custom": [
      {
        "key": "t_shirt_size",
        "label": "T-shirt size",
        "type": "select",
        "tier": "public",
        "value": "M"
      },
      {
        "key": "remote",
        "label": "Remote allowance",
        "type": "boolean",
        "tier": "job",
        "value": null
      }
    ],
    "job": {
      "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"
        }
      ]
    },
    "history": [
      {
        "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"
          }
        ]
      }
    ],
    "reports": [],
    "visible_tiers": [
      "public",
      "job"
    ],
    "planned": null,
    "missing": [],
    "dotted_managers": [
      {
        "id": "p7",
        "name": "João Pereira",
        "title": "Sales Lead",
        "photo_url": null
      }
    ],
    "dotted_reports": []
  }
}

Upload a person's photo#

POST/v1/org/people.photo.uploadWrite

Sets the profile photo of a person (owners, admins and HR). The image (image_base64: the file as base64) must be a JPEG, PNG or WebP of at most 2 MB and 24 megapixels (over MCP the request is limited to 2 MiB, so about 1.5 MB; send larger files through the REST API); the server checks the bytes, centre-crops it to a square, re-encodes it as a 512×512 WebP and drops all metadata (EXIF, location). A new upload replaces the old photo. The photo is visible to everyone in the organization who can see the person (public tier, also over the API and MCP as photo_url); never outside it. Returns the new photo_url (a path on the company address, fetched with the same credentials). Errors: not_found for unknown or erased people, validation_failed for an image that is not JPEG/PNG/WebP, too large or damaged, rate_limited when the server is busy with other images (retry in a few seconds). Use dry_run to check the image without saving it.

Who can call it
Manage key owner admin hr
MCP tool
org_people_photo_upload 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
Body limit
3 MiB (other actions: 2 MiB)

Input

  • person_idstringrequired
  • image_base64stringrequired

    The image file as base64 (a data: URL is accepted): JPEG, PNG or WebP, at most 2 MB. Square images work best; the server centre-crops.

    1–2900000 characters.

Returns

  • person_idstringrequired
  • photo_urlstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict payload_too_large rate_limited internal

curl
curl https://api.bizisy.com/v1/org/people.photo.upload \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"person_id":"p1","image_base64":"UklGRg=="}'
Response
{
  "data": {
    "person_id": "p1",
    "photo_url": "https://acme.bizisy.com/api/photos/people/p1?v=01k0000000000000000000000d"
  }
}

Remove a person's photo#

POST/v1/org/people.photo.removeDestructive

Deletes the profile photo of a person (owners, admins and HR); their initials show instead. Succeeds when there is no photo. Errors: not_found for unknown or erased people.

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

  • person_idstringrequired

Returns

  • person_idstringrequired
  • photo_urlstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/people.photo.remove \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"person_id":"p1"}'
Response
{
  "data": {
    "person_id": "p1",
    "photo_url": null
  }
}

Move people to a new manager, team or location#

POST/v1/org/people.moveWrite

Moves one or more people (at most 50 per call) from effective_date (YYYY-MM-DD): a new manager_id (or null for none), unit_id (team) and/or location_id. Moving into a team without manager_id makes that team's lead each person's manager (as org_people_change_job does). reason defaults to transfer when the team changes, else change. Returns preview (summary, every field that changes per person with before and after, who must approve, and who is blocked and why) and people[] with each one's status: applied, requested (sent for approval), unchanged (already so) or blocked. Use dry_run first and show the preview. If anyone is blocked (not employed that day, a reporting cycle, a change already waiting for approval…), the real call is refused (conflict, details.blocked) unless skip_blocked is true, which moves the others. When Settings → Approval rules requires approval for job changes, each person gets their own request with their own approver. Owners, admins and HR; a manager (in My workspace) can propose it for people in their team, and HR always decides.

Who can call it
Manage key any Manage role
Me key anyone
MCP tool
org_people_move on HR Assistant, My Workplace
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

  • person_idsstring[]required

    1–50 items.

  • effective_datestringrequired
  • manager_idstring | null
  • unit_idstring
  • location_idstring
  • reason"change" | "transfer"
  • skip_blockedboolean

Returns

  • previewobjectrequired
    4 fields
    • summarystringrequired
    • changesobject[]required
      6 fields
      • personobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • fieldstringrequired
      • labelstringrequired
      • fromstring | nullrequired
      • tostring | nullrequired
      • effectivestringrequired
    • approvals_neededobject[]required
      3 fields
      • personobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • waiting_for"manager" | "hr"required
      • approversstring[]required
    • blockedobject[]required
      2 fields
      • personobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • reasonstringrequired
  • peopleobject[]required
    3 fields
    • idstringrequired
    • namestringrequired
    • status"applied" | "requested" | "unchanged" | "blocked"required

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/people.move \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "person_ids": [
    "p1"
  ],
  "effective_date": "2026-11-01",
  "manager_id": null,
  "reason": "change",
  "skip_blocked": true
}'
Response
{
  "data": {
    "people": [
      {
        "id": "p1",
        "name": "Ana Ferreira",
        "status": "applied"
      },
      {
        "id": "p2",
        "name": "Bea Silva",
        "status": "blocked"
      }
    ],
    "preview": {
      "summary": "1 person moves to Product from 1 Nov 2026.",
      "changes": [],
      "approvals_needed": [],
      "blocked": [
        {
          "person": {
            "id": "p2",
            "name": "Bea Silva"
          },
          "reason": "Bea Silva already has a change waiting for approval."
        }
      ]
    }
  }
}

Mark someone as leaving#

POST/v1/org/people.mark_leavingDestructive

Ends a person's employment after last_day (inclusive, YYYY-MM-DD, may be in the future) and takes care of what follows, in one change: each direct report gets a new manager from the day after (reassign [{person_id, manager_id or null}]; anyone not listed goes to the leaver's own manager, or none), replacement_position true opens a position for their role (their title, team and location, to start the day after), and access decides their Bizisy login: after_last_day (default: it stops working at midnight after the last day, company time), now (owners and admins only) or keep. The offboarding checklists that start by themselves start. reason is free text (e.g. resigned); leaving_type is why, structured (resignation, retirement, dismissal, redundancy, end_of_contract, mutual_agreement, death, other), for the turnover split in Reports. Returns preview (every change with before and after, who must approve) and warnings. Use dry_run first and show the preview. When Settings → Approval rules requires approval for terminations, one request holds all of it and it applies when approved. Use it instead of org_people_terminate. Owners, admins and HR; a manager (in My workspace) can propose it for someone in their team (a resignation: last day and reason; no replacement position, no ending the login now), and HR always decides.

Who can call it
Manage key any Manage role
Me key anyone
MCP tool
org_people_mark_leaving on HR Assistant, My Workplace
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

  • person_idstringrequired
  • last_daystringrequired
  • reasonstring

    Up to 200 characters.

  • leaving_typestring (enum)

    Why they leave: resignation, retirement (voluntary); dismissal, redundancy, end_of_contract (involuntary); mutual_agreement, death, other. Splits turnover in Reports. null or absent: not recorded (a termination it replaces keeps its type).

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

  • reassignobject[]

    Up to 500 items.

    2 fields
    • person_idstringrequired
    • manager_idstring | nullrequired
  • replacement_positionboolean
  • access"after_last_day" | "now" | "keep"
  • person_toldboolean

    Whether the person has already been told about this last day. false: it stays with HR and their manager (Home asks to tell them) until someone marks them told with org_people_mark_told or the day passes; until then they see no last day, reason, offboarding task or time off change. Absent: true for resignation, retirement, mutual_agreement and death, false otherwise (a moved termination keeps its own).

  • 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

  • personobjectrequired
    35 fields
    • idstringrequired
    • namestringrequired
    • given_namestringrequired
    • family_namestringrequired
    • preferred_namestring | nullrequired
    • work_emailstringrequired
    • titlestring | nullrequired
    • status"invited" | "pre_hire" | "active" | "terminated" | "none"required

      invited: waiting for their details (names, title, start date), not employed yet; pre_hire: starts later; active; terminated: has left; none: no job.

    • start_datestring | nullrequired
    • unitobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • locationobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • managerobject | nullrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • invitedbooleanrequired
    • has_loginbooleanrequired
    • photo_urlstring | nullrequired
    • pronounsstring | nullrequired
    • work_phonestring | nullrequired
    • personal_emailstring | nullrequired
    • personal_phonestring | nullrequired
    • addressobject | nullrequired
      5 fields
      • line1stringrequired
      • line2string
      • citystringrequired
      • postal_codestring
      • countrystringrequired
    • birthdaystring | nullrequired
    • sex"female" | "male" | "another" | "undisclosed"required

      For equal-pay reporting only (private: the person, owners, admins and HR in the app). female and male are compared; another and undisclosed are counted, not compared.

    • emergency_contactsobject[] | nullrequired
      3 fields
      • namestringrequired
      • relationshipstringrequired
      • phonestringrequired
    • tax_idstring | nullrequired
    • social_security_numberstring | nullrequired
    • ibanstring | nullrequired
    • customobject[]required
      7 fields
      • keystringrequired
      • labelstringrequired
      • typestring (enum)required

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

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

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

      • fileobject | null

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

        4 fields
        • namestring | nullrequired

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

        • sizeintegerrequired
        • content_typestringrequired
        • previewablebooleanrequired

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

      • personobject | null

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

        4 fields
        • idstringrequired
        • namestringrequired
        • titlestring | nullrequired
        • photo_urlstring | nullrequired
    • 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.

    • historyobject[] | 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.

    • reportsobject[]required
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • visible_tiers"public" | "private" | "job" | "pay"[]required
    • plannedobject | nullrequired

      While invited (status invited): the job details known so far (job tier; null otherwise or when not visible).

      14 fields
      • titlestring | nullrequired
      • title_idstring | nullrequired
      • start_datestring | nullrequired
      • 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
      • ftenumber | nullrequired
      • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
      • contract_end_datestring | nullrequired
      • probation_end_datestring | nullrequired
      • weekly_hoursnumber | nullrequired
      • notice_period_daysinteger | nullrequired
    • missing"given_name" | "family_name" | "title" | "start_date"[]required

      While invited: what is still needed to register them (given_name, family_name, title, start_date); [] otherwise.

    • dotted_managersobject[]required

      Dotted-line managers today (spec structure-over-time D10): they see job details, never approve.

      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • dotted_reportsobject[]required

      People this person has a dotted line to today.

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

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/people.mark_leaving \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "person_id": "p1",
  "last_day": "2026-11-21",
  "reason": "resigned",
  "reassign": [
    {
      "person_id": "p2",
      "manager_id": null
    }
  ],
  "replacement_position": true,
  "access": "now"
}'
Response
{
  "data": {
    "person": {
      "id": "p1",
      "name": "Ana Ferreira",
      "given_name": "Ana",
      "family_name": "Ferreira",
      "preferred_name": null,
      "work_email": "ana@acme.test",
      "title": "Engineer",
      "status": "active",
      "start_date": "2024-01-15",
      "unit": {
        "id": "u2",
        "name": "Engineering"
      },
      "location": {
        "id": "l1",
        "name": "Head office"
      },
      "manager": {
        "id": "p2",
        "name": "Rui Costa",
        "title": "CTO",
        "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
      },
      "invited": true,
      "has_login": true,
      "photo_url": null,
      "pronouns": "she/her",
      "work_phone": "+351 210 000 000",
      "personal_email": null,
      "personal_phone": null,
      "address": null,
      "birthday": null,
      "sex": "female",
      "emergency_contacts": null,
      "tax_id": null,
      "social_security_number": null,
      "iban": null,
      "custom": [
        {
          "key": "t_shirt_size",
          "label": "T-shirt size",
          "type": "select",
          "tier": "public",
          "value": "M"
        },
        {
          "key": "remote",
          "label": "Remote allowance",
          "type": "boolean",
          "tier": "job",
          "value": null
        }
      ],
      "job": {
        "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"
          }
        ]
      },
      "history": [
        {
          "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"
            }
          ]
        }
      ],
      "reports": [],
      "visible_tiers": [
        "public",
        "job"
      ],
      "planned": null,
      "missing": [],
      "dotted_managers": [
        {
          "id": "p7",
          "name": "João Pereira",
          "title": "Sales Lead",
          "photo_url": null
        }
      ],
      "dotted_reports": []
    },
    "approval": null,
    "warnings": [],
    "preview": {
      "summary": "Ana Ferreira leaves after 21 Nov 2026; 1 person gets a new manager from 22 Nov 2026.",
      "changes": [
        {
          "person": {
            "id": "p1",
            "name": "Ana Ferreira"
          },
          "field": "last_day",
          "label": "Last working day",
          "from": null,
          "to": "2026-11-21",
          "effective": "2026-11-21"
        }
      ],
      "approvals_needed": [],
      "blocked": []
    }
  }
}

Promote or give a raise#

POST/v1/org/people.promoteWrite

A promotion or raise in one change, from effective_date (YYYY-MM-DD): a new title (optional; reason defaults to promotion) and/or new pay, either {amount, currency, period} or {percent} of the pay in force that day (−50 to +200). note goes with the pay row. Pay follows the rules of org_pay_add (never your own; an HR member's pay only by an owner or admin; an owner's only by another owner). When approval is needed for job changes or pay, one request holds both and HR decides it last (a manager step sees only the job part). Over an API key or MCP, pay is accepted only as a request HR decides in Bizisy, even when approval is off, and the result never shows amounts (pay is null). Returns preview (what changes; pay only for those who may see it) and approval. Use dry_run first. Owners, admins and HR; a manager (in My workspace) can propose a new title for someone in their team (never pay), and HR always decides.

Who can call it
Manage key any Manage role
Me key anyone
MCP tool
org_people_promote on HR Assistant, My Workplace
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

  • person_idstringrequired
  • effective_datestringrequired
  • titlestring

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

    1–120 characters.

  • title_idstring

    A job title from org_titles_list, instead of title.

  • display_titlestring | null

    A different title to show on the profile, chart and directory (reports use the catalog title); null removes it. Cleared when the catalog title changes, unless sent.

    1–120 characters.

  • create_titleboolean

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

  • reason"promotion" | "change"
  • payobject
    4 fields (one of several shapes)

    Option 1

    • amountnumberrequired

      From 0 to 100000000.

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

    Option 2

    • percentnumberrequired

      From -50 to 200.

  • notestring

    Up to 200 characters.

Returns

  • personobjectrequired
    35 fields
    • idstringrequired
    • namestringrequired
    • given_namestringrequired
    • family_namestringrequired
    • preferred_namestring | nullrequired
    • work_emailstringrequired
    • titlestring | nullrequired
    • status"invited" | "pre_hire" | "active" | "terminated" | "none"required

      invited: waiting for their details (names, title, start date), not employed yet; pre_hire: starts later; active; terminated: has left; none: no job.

    • start_datestring | nullrequired
    • unitobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • locationobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • managerobject | nullrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • invitedbooleanrequired
    • has_loginbooleanrequired
    • photo_urlstring | nullrequired
    • pronounsstring | nullrequired
    • work_phonestring | nullrequired
    • personal_emailstring | nullrequired
    • personal_phonestring | nullrequired
    • addressobject | nullrequired
      5 fields
      • line1stringrequired
      • line2string
      • citystringrequired
      • postal_codestring
      • countrystringrequired
    • birthdaystring | nullrequired
    • sex"female" | "male" | "another" | "undisclosed"required

      For equal-pay reporting only (private: the person, owners, admins and HR in the app). female and male are compared; another and undisclosed are counted, not compared.

    • emergency_contactsobject[] | nullrequired
      3 fields
      • namestringrequired
      • relationshipstringrequired
      • phonestringrequired
    • tax_idstring | nullrequired
    • social_security_numberstring | nullrequired
    • ibanstring | nullrequired
    • customobject[]required
      7 fields
      • keystringrequired
      • labelstringrequired
      • typestring (enum)required

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

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

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

      • fileobject | null

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

        4 fields
        • namestring | nullrequired

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

        • sizeintegerrequired
        • content_typestringrequired
        • previewablebooleanrequired

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

      • personobject | null

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

        4 fields
        • idstringrequired
        • namestringrequired
        • titlestring | nullrequired
        • photo_urlstring | nullrequired
    • 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.

    • historyobject[] | 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.

    • reportsobject[]required
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • visible_tiers"public" | "private" | "job" | "pay"[]required
    • plannedobject | nullrequired

      While invited (status invited): the job details known so far (job tier; null otherwise or when not visible).

      14 fields
      • titlestring | nullrequired
      • title_idstring | nullrequired
      • start_datestring | nullrequired
      • 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
      • ftenumber | nullrequired
      • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
      • contract_end_datestring | nullrequired
      • probation_end_datestring | nullrequired
      • weekly_hoursnumber | nullrequired
      • notice_period_daysinteger | nullrequired
    • missing"given_name" | "family_name" | "title" | "start_date"[]required

      While invited: what is still needed to register them (given_name, family_name, title, start_date); [] otherwise.

    • dotted_managersobject[]required

      Dotted-line managers today (spec structure-over-time D10): they see job details, never approve.

      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • dotted_reportsobject[]required

      People this person has a dotted line to today.

      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
  • approvalobject | nullrequired
    11 fields
    • idstringrequired
    • status"pending" | "approved"required
    • waiting_for"manager" | "hr"required
    • approversstring[]required
    • automaticbooleanrequired
    • note"proposed_by_approver" | "no_other_approver"required
    • fallbackbooleanrequired
    • team_leadobject | nullrequired
      3 fields
      • unit_idstringrequired
      • unit_namestringrequired
      • reason"no_manager" | "manager_left"required
    • team_lead_blockedobject | nullrequired
      3 fields
      • unit_idstringrequired
      • unit_namestringrequired
      • what"lead" | "removed" | "moved" | "archived"required
    • untrusted"no_login" | "invited_by_proposer"required
    • then"manager" | "hr"required
  • previewobjectrequired
    4 fields
    • summarystringrequired
    • changesobject[]required
      6 fields
      • personobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • fieldstringrequired
      • labelstringrequired
      • fromstring | nullrequired
      • tostring | nullrequired
      • effectivestringrequired
    • approvals_neededobject[]required
      3 fields
      • personobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • waiting_for"manager" | "hr"required
      • approversstring[]required
    • blockedobject[]required
      2 fields
      • personobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • reasonstringrequired
  • payobject | nullrequired
    2 fields
    • currentobject | nullrequired
      8 fields
      • idstringrequired
      • valid_fromstringrequired
      • valid_tostring | nullrequired
      • amountnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
      • notestring | nullrequired
      • created_atstringrequired
    • historyobject[]required
      8 fields
      • idstringrequired
      • valid_fromstringrequired
      • valid_tostring | nullrequired
      • amountnumberrequired
      • currencystringrequired
      • period"year" | "month" | "hour"required
      • notestring | nullrequired
      • created_atstringrequired
  • title_matchobject | nullrequired

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

    5 fields
    • idstring | nullrequired

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

    • namestringrequired
    • createdbooleanrequired

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

    • matched_fromstring

      What was typed, when the catalog names it differently.

    • similarobject[]

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

      3 fields
      • idstringrequired
      • namestringrequired
      • peopleinteger | nullrequired

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

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/people.promote \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "person_id": "p1",
  "effective_date": "2026-11-01",
  "title": "Lead",
  "reason": "promotion",
  "pay": {
    "amount": 4000,
    "currency": "EUR",
    "period": "month"
  }
}'
Response
{
  "data": {
    "person": {
      "id": "p1",
      "name": "Ana Ferreira",
      "given_name": "Ana",
      "family_name": "Ferreira",
      "preferred_name": null,
      "work_email": "ana@acme.test",
      "title": "Engineer",
      "status": "active",
      "start_date": "2024-01-15",
      "unit": {
        "id": "u2",
        "name": "Engineering"
      },
      "location": {
        "id": "l1",
        "name": "Head office"
      },
      "manager": {
        "id": "p2",
        "name": "Rui Costa",
        "title": "CTO",
        "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
      },
      "invited": true,
      "has_login": true,
      "photo_url": null,
      "pronouns": "she/her",
      "work_phone": "+351 210 000 000",
      "personal_email": null,
      "personal_phone": null,
      "address": null,
      "birthday": null,
      "sex": "female",
      "emergency_contacts": null,
      "tax_id": null,
      "social_security_number": null,
      "iban": null,
      "custom": [
        {
          "key": "t_shirt_size",
          "label": "T-shirt size",
          "type": "select",
          "tier": "public",
          "value": "M"
        },
        {
          "key": "remote",
          "label": "Remote allowance",
          "type": "boolean",
          "tier": "job",
          "value": null
        }
      ],
      "job": {
        "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"
          }
        ]
      },
      "history": [
        {
          "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"
            }
          ]
        }
      ],
      "reports": [],
      "visible_tiers": [
        "public",
        "job"
      ],
      "planned": null,
      "missing": [],
      "dotted_managers": [
        {
          "id": "p7",
          "name": "João Pereira",
          "title": "Sales Lead",
          "photo_url": null
        }
      ],
      "dotted_reports": []
    },
    "approval": null,
    "title_match": null,
    "pay": {
      "current": {
        "id": "pay1",
        "valid_from": "2024-01-15",
        "valid_to": null,
        "amount": 42000,
        "currency": "EUR",
        "period": "year",
        "note": null,
        "created_at": "2026-10-04T10:00:00.000Z"
      },
      "history": [
        {
          "id": "pay1",
          "valid_from": "2024-01-15",
          "valid_to": null,
          "amount": 42000,
          "currency": "EUR",
          "period": "year",
          "note": null,
          "created_at": "2026-10-04T10:00:00.000Z"
        }
      ]
    },
    "preview": {
      "summary": "Ana Ferreira: new title Senior Engineer from 1 Nov 2026.",
      "changes": [
        {
          "person": {
            "id": "p1",
            "name": "Ana Ferreira"
          },
          "field": "title",
          "label": "Title",
          "from": "Engineer",
          "to": "Senior Engineer",
          "effective": "2026-11-01"
        }
      ],
      "approvals_needed": [],
      "blocked": []
    }
  }
}

Decide on a probation#

POST/v1/org/people.probation_decideWrite

The outcome of someone's probation (trial period), as HR practice has it: passed (confirmed; Home, reminders and My team stop asking), extend (new_end_date: the probation end on their current contract moves; it follows the job-change approval rule), or end (last_day: they leave as with org_people_mark_leaving, reason "Did not pass probation"). note is kept with the decision. For people employed through a Portuguese legal entity, legal gives the Código do Trabalho rules (art. 112–114): the notice to end a trial period now (no notice up to 60 days served, 7 days after 60, 15 after 120) and the 240-day maximum; warnings say when a choice goes against them (Bizisy never changes it for you). Owners, admins and HR decide; a manager (in My workspace) proposes it for someone in their team and HR decides. Use dry_run first.

Who can call it
Manage key any Manage role
Me key anyone
MCP tool
org_people_probation_decide on HR Assistant, My Workplace
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

  • person_idstringrequired
  • outcome"passed" | "extend" | "end"required
  • new_end_datestring
  • last_daystring
  • notestring

    Up to 500 characters.

  • person_toldboolean

    Whether the person has already been told about this last day. false: it stays with HR and their manager (Home asks to tell them) until someone marks them told with org_people_mark_told or the day passes; until then they see no last day, reason, offboarding task or time off change. Absent: true for resignation, retirement, mutual_agreement and death, false otherwise (a moved termination keeps its own).

Returns

  • personobjectrequired
    35 fields
    • idstringrequired
    • namestringrequired
    • given_namestringrequired
    • family_namestringrequired
    • preferred_namestring | nullrequired
    • work_emailstringrequired
    • titlestring | nullrequired
    • status"invited" | "pre_hire" | "active" | "terminated" | "none"required

      invited: waiting for their details (names, title, start date), not employed yet; pre_hire: starts later; active; terminated: has left; none: no job.

    • start_datestring | nullrequired
    • unitobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • locationobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • managerobject | nullrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • invitedbooleanrequired
    • has_loginbooleanrequired
    • photo_urlstring | nullrequired
    • pronounsstring | nullrequired
    • work_phonestring | nullrequired
    • personal_emailstring | nullrequired
    • personal_phonestring | nullrequired
    • addressobject | nullrequired
      5 fields
      • line1stringrequired
      • line2string
      • citystringrequired
      • postal_codestring
      • countrystringrequired
    • birthdaystring | nullrequired
    • sex"female" | "male" | "another" | "undisclosed"required

      For equal-pay reporting only (private: the person, owners, admins and HR in the app). female and male are compared; another and undisclosed are counted, not compared.

    • emergency_contactsobject[] | nullrequired
      3 fields
      • namestringrequired
      • relationshipstringrequired
      • phonestringrequired
    • tax_idstring | nullrequired
    • social_security_numberstring | nullrequired
    • ibanstring | nullrequired
    • customobject[]required
      7 fields
      • keystringrequired
      • labelstringrequired
      • typestring (enum)required

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

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

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

      • fileobject | null

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

        4 fields
        • namestring | nullrequired

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

        • sizeintegerrequired
        • content_typestringrequired
        • previewablebooleanrequired

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

      • personobject | null

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

        4 fields
        • idstringrequired
        • namestringrequired
        • titlestring | nullrequired
        • photo_urlstring | nullrequired
    • 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.

    • historyobject[] | 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.

    • reportsobject[]required
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • visible_tiers"public" | "private" | "job" | "pay"[]required
    • plannedobject | nullrequired

      While invited (status invited): the job details known so far (job tier; null otherwise or when not visible).

      14 fields
      • titlestring | nullrequired
      • title_idstring | nullrequired
      • start_datestring | nullrequired
      • 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
      • ftenumber | nullrequired
      • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
      • contract_end_datestring | nullrequired
      • probation_end_datestring | nullrequired
      • weekly_hoursnumber | nullrequired
      • notice_period_daysinteger | nullrequired
    • missing"given_name" | "family_name" | "title" | "start_date"[]required

      While invited: what is still needed to register them (given_name, family_name, title, start_date); [] otherwise.

    • dotted_managersobject[]required

      Dotted-line managers today (spec structure-over-time D10): they see job details, never approve.

      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • dotted_reportsobject[]required

      People this person has a dotted line to today.

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

    Things to check before going ahead, such as Portuguese legal limits (warnings, never refusals).

  • legalobject | nullrequired
    4 fields
    • countrystringrequired
    • days_servedintegerrequired
    • probation_notice_daysintegerrequired
    • probation_max_endstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/people.probation_decide \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "person_id": "p1",
  "outcome": "extend",
  "new_end_date": "2026-12-31",
  "note": "More time on the sales targets"
}'
Response
{
  "data": {
    "person": {
      "id": "p1",
      "name": "Ana Ferreira",
      "given_name": "Ana",
      "family_name": "Ferreira",
      "preferred_name": null,
      "work_email": "ana@acme.test",
      "title": "Engineer",
      "status": "active",
      "start_date": "2024-01-15",
      "unit": {
        "id": "u2",
        "name": "Engineering"
      },
      "location": {
        "id": "l1",
        "name": "Head office"
      },
      "manager": {
        "id": "p2",
        "name": "Rui Costa",
        "title": "CTO",
        "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
      },
      "invited": true,
      "has_login": true,
      "photo_url": null,
      "pronouns": "she/her",
      "work_phone": "+351 210 000 000",
      "personal_email": null,
      "personal_phone": null,
      "address": null,
      "birthday": null,
      "sex": "female",
      "emergency_contacts": null,
      "tax_id": null,
      "social_security_number": null,
      "iban": null,
      "custom": [
        {
          "key": "t_shirt_size",
          "label": "T-shirt size",
          "type": "select",
          "tier": "public",
          "value": "M"
        },
        {
          "key": "remote",
          "label": "Remote allowance",
          "type": "boolean",
          "tier": "job",
          "value": null
        }
      ],
      "job": {
        "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"
          }
        ]
      },
      "history": [
        {
          "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"
            }
          ]
        }
      ],
      "reports": [],
      "visible_tiers": [
        "public",
        "job"
      ],
      "planned": null,
      "missing": [],
      "dotted_managers": [
        {
          "id": "p7",
          "name": "João Pereira",
          "title": "Sales Lead",
          "photo_url": null
        }
      ],
      "dotted_reports": []
    },
    "approval": null,
    "warnings": [],
    "legal": {
      "country": "PT",
      "days_served": 95,
      "probation_notice_days": 7,
      "probation_max_end": "2027-02-26"
    },
    "preview": {
      "summary": "Ana Ferreira passes probation.",
      "changes": [
        {
          "person": {
            "id": "p1",
            "name": "Ana Ferreira"
          },
          "field": "probation",
          "label": "Probation",
          "from": "Ends 20 Oct 2026",
          "to": "Passed",
          "effective": "2026-10-04"
        }
      ],
      "approvals_needed": [],
      "blocked": []
    }
  }
}

Decide on a fixed-term contract#

POST/v1/org/people.contract_decideWrite

What happens when someone's fixed-term contract (contract_end_date on their current job) ends, as HR practice has it: renew (new_end_date: a job change from the day after the current end, so each renewal shows in the history), permanent (contract_type permanent and no end date, from effective_date, default the day after the end) or end (they leave on the contract end date, as with org_people_mark_leaving, reason "End of fixed-term contract"). For people employed through a Portuguese legal entity, warnings apply the Código do Trabalho (2023): at most 2 years and 3 renewals, renewals in total no longer than the first term, and written notice 15 days before the end to let it end. Changes follow the approval rules. Owners, admins and HR. Use dry_run first.

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

  • person_idstringrequired
  • outcome"renew" | "permanent" | "end"required
  • new_end_datestring
  • effective_datestring
  • person_toldboolean

    Whether the person has already been told about this last day. false: it stays with HR and their manager (Home asks to tell them) until someone marks them told with org_people_mark_told or the day passes; until then they see no last day, reason, offboarding task or time off change. Absent: true for resignation, retirement, mutual_agreement and death, false otherwise (a moved termination keeps its own).

Returns

  • personobjectrequired
    35 fields
    • idstringrequired
    • namestringrequired
    • given_namestringrequired
    • family_namestringrequired
    • preferred_namestring | nullrequired
    • work_emailstringrequired
    • titlestring | nullrequired
    • status"invited" | "pre_hire" | "active" | "terminated" | "none"required

      invited: waiting for their details (names, title, start date), not employed yet; pre_hire: starts later; active; terminated: has left; none: no job.

    • start_datestring | nullrequired
    • unitobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • locationobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • managerobject | nullrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • invitedbooleanrequired
    • has_loginbooleanrequired
    • photo_urlstring | nullrequired
    • pronounsstring | nullrequired
    • work_phonestring | nullrequired
    • personal_emailstring | nullrequired
    • personal_phonestring | nullrequired
    • addressobject | nullrequired
      5 fields
      • line1stringrequired
      • line2string
      • citystringrequired
      • postal_codestring
      • countrystringrequired
    • birthdaystring | nullrequired
    • sex"female" | "male" | "another" | "undisclosed"required

      For equal-pay reporting only (private: the person, owners, admins and HR in the app). female and male are compared; another and undisclosed are counted, not compared.

    • emergency_contactsobject[] | nullrequired
      3 fields
      • namestringrequired
      • relationshipstringrequired
      • phonestringrequired
    • tax_idstring | nullrequired
    • social_security_numberstring | nullrequired
    • ibanstring | nullrequired
    • customobject[]required
      7 fields
      • keystringrequired
      • labelstringrequired
      • typestring (enum)required

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

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

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

      • fileobject | null

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

        4 fields
        • namestring | nullrequired

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

        • sizeintegerrequired
        • content_typestringrequired
        • previewablebooleanrequired

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

      • personobject | null

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

        4 fields
        • idstringrequired
        • namestringrequired
        • titlestring | nullrequired
        • photo_urlstring | nullrequired
    • 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.

    • historyobject[] | 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.

    • reportsobject[]required
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • visible_tiers"public" | "private" | "job" | "pay"[]required
    • plannedobject | nullrequired

      While invited (status invited): the job details known so far (job tier; null otherwise or when not visible).

      14 fields
      • titlestring | nullrequired
      • title_idstring | nullrequired
      • start_datestring | nullrequired
      • 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
      • ftenumber | nullrequired
      • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
      • contract_end_datestring | nullrequired
      • probation_end_datestring | nullrequired
      • weekly_hoursnumber | nullrequired
      • notice_period_daysinteger | nullrequired
    • missing"given_name" | "family_name" | "title" | "start_date"[]required

      While invited: what is still needed to register them (given_name, family_name, title, start_date); [] otherwise.

    • dotted_managersobject[]required

      Dotted-line managers today (spec structure-over-time D10): they see job details, never approve.

      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • dotted_reportsobject[]required

      People this person has a dotted line to today.

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

    Things to check before going ahead, such as Portuguese legal limits (warnings, never refusals).

  • legalobject | nullrequired
    4 fields
    • countrystringrequired
    • days_servedintegerrequired
    • probation_notice_daysintegerrequired
    • probation_max_endstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/people.contract_decide \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"person_id":"p1","outcome":"permanent","effective_date":"2026-11-01"}'
Response
{
  "data": {
    "person": {
      "id": "p1",
      "name": "Ana Ferreira",
      "given_name": "Ana",
      "family_name": "Ferreira",
      "preferred_name": null,
      "work_email": "ana@acme.test",
      "title": "Engineer",
      "status": "active",
      "start_date": "2024-01-15",
      "unit": {
        "id": "u2",
        "name": "Engineering"
      },
      "location": {
        "id": "l1",
        "name": "Head office"
      },
      "manager": {
        "id": "p2",
        "name": "Rui Costa",
        "title": "CTO",
        "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
      },
      "invited": true,
      "has_login": true,
      "photo_url": null,
      "pronouns": "she/her",
      "work_phone": "+351 210 000 000",
      "personal_email": null,
      "personal_phone": null,
      "address": null,
      "birthday": null,
      "sex": "female",
      "emergency_contacts": null,
      "tax_id": null,
      "social_security_number": null,
      "iban": null,
      "custom": [
        {
          "key": "t_shirt_size",
          "label": "T-shirt size",
          "type": "select",
          "tier": "public",
          "value": "M"
        },
        {
          "key": "remote",
          "label": "Remote allowance",
          "type": "boolean",
          "tier": "job",
          "value": null
        }
      ],
      "job": {
        "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"
          }
        ]
      },
      "history": [
        {
          "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"
            }
          ]
        }
      ],
      "reports": [],
      "visible_tiers": [
        "public",
        "job"
      ],
      "planned": null,
      "missing": [],
      "dotted_managers": [
        {
          "id": "p7",
          "name": "João Pereira",
          "title": "Sales Lead",
          "photo_url": null
        }
      ],
      "dotted_reports": []
    },
    "approval": null,
    "warnings": [
      "In Portugal a fixed-term contract lasts at most 2 years in total, renewals included (Código do Trabalho, art. 148)."
    ],
    "legal": null,
    "preview": {
      "summary": "Ana Ferreira's contract is renewed until 31 Oct 2027.",
      "changes": [],
      "approvals_needed": [],
      "blocked": []
    }
  }
}

Find people, teams, locations and positions#

POST/v1/org/findRead

Finds what a name refers to, in one call: people (by name, preferred name, email or title), teams, locations, open positions and legal entities whose name contains q (2+ characters; accents and case ignored). kinds limits the search. Each result has kind, id, name and a short detail (title and team, a team's parent, a position's status). Leavers are included with status terminated; erased people never. Open positions only for those who may see them. Use the ids with the other tools.

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

Input

  • qstringrequired

    2–100 characters.

  • kinds"person" | "team" | "location" | "position" | "legal_entity"[]

    At least 1 item.

  • limitinteger

    From 1 to 50.

Returns

  • resultsobject[]required
    5 fields
    • kind"person" | "team" | "location" | "position" | "legal_entity"required
    • idstringrequired
    • namestringrequired
    • detailstring | nullrequired
    • statusstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/find \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"eng","kinds":["team","position"],"limit":5}'
Response
{
  "data": {
    "results": [
      {
        "kind": "person",
        "id": "p1",
        "name": "João Pereira",
        "detail": "Engineer · Platform",
        "status": "active"
      },
      {
        "kind": "team",
        "id": "u1",
        "name": "Engineering",
        "detail": null,
        "status": null
      }
    ]
  }
}

Query people (filters, columns, pages)#

POST/v1/org/people.queryRead

Lists people with the filters and fields you choose, a page at a time (limit up to 200, offset; total says how many match). Filters (combined with AND): status (default active and starting soon; terminated or all for leavers; invited for people invited by email who are still waiting for their details), unit_id (include_subunits for every team below), manager_id, location_id, title_id (a job title from org_titles_list; titles merged into it count too), starts_between {from, to}, and job-detail filters on_probation (true: a probation end date today or later), probation_ends_between, contract_ends_between. columns picks fields: title, unit, manager, location, start_date, employment_type, fte, contract_type, contract_end_date, probation_end_date (default title, unit, manager). Job details (employment_type, fte, contract_type, contract_end_date, probation_end_date and the job filters) count only for people whose job details you may see — yourself, people you manage, everyone for owners, admins and HR; for others those columns are null and the job filters leave them out. group_id: members of a saved group (org_groups_list) today, as you see them. Never private or pay data. Dates as of today.

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

Input

  • status"active" | "pre_hire" | "terminated" | "invited" | "all"
  • unit_idstring
  • include_subunitsboolean
  • manager_idstring
  • location_idstring
  • title_idstring
  • starts_betweenobject
    2 fields
    • fromstringrequired
    • tostringrequired
  • on_probationboolean
  • probation_ends_betweenobject
    2 fields
    • fromstringrequired
    • tostringrequired
  • contract_ends_betweenobject
    2 fields
    • fromstringrequired
    • tostringrequired
  • group_idstring
  • columnsstring (enum)[]

    One of: title, unit, manager, location, start_date, employment_type, fte, contract_type, contract_end_date, probation_end_date. 1–10 items.

  • limitinteger

    From 1 to 200.

  • offsetinteger

    At least 0.

Returns

  • totalintegerrequired
  • offsetintegerrequired
  • next_offsetinteger | nullrequired
  • peopleobject[]required

    The chosen columns only.

    13 fields
    • idstringrequired
    • namestringrequired
    • statusstringrequired
    • titlestring | number | "null"
    • unitstring | number | "null"
    • managerstring | number | "null"
    • locationstring | number | "null"
    • start_datestring | number | "null"
    • employment_typestring | number | "null"
    • ftestring | number | "null"
    • contract_typestring | number | "null"
    • contract_end_datestring | number | "null"
    • probation_end_datestring | number | "null"

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/people.query \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "all",
  "unit_id": "u1",
  "include_subunits": true,
  "on_probation": true,
  "probation_ends_between": {
    "from": "2026-10-01",
    "to": "2026-12-31"
  },
  "columns": [
    "probation_end_date",
    "manager"
  ],
  "limit": 100,
  "offset": 0
}'
Response
{
  "data": {
    "total": 3,
    "offset": 0,
    "next_offset": 2,
    "people": [
      {
        "id": "p1",
        "name": "Ana Ferreira",
        "status": "active",
        "title": "Engineer",
        "unit": "Platform",
        "manager": null
      },
      {
        "id": "p2",
        "name": "Bea Silva",
        "status": "active",
        "title": "Lead",
        "unit": "Platform",
        "manager": "Ana Ferreira"
      }
    ]
  }
}

A person's journey#

POST/v1/org/people.journeyRead

Where a person is in their employment, from hire to leaving: stage (hired: before the start date; onboarding: an onboarding checklist is open; probation: until probation_end_date; employed; leaving: a last day is set; former), every stage with done/current/upcoming/skipped, its date and checklist progress, next (the one thing coming: the start, the next onboarding task, the probation end, the contract end, the work anniversary or the last day, with the person-page tab to act on it) and timeline (newest first: hired, rehired, promotion, transfer, change with what changed, pay changes (only for those who see pay: the person and owners, admins and HR in the app), probation ended, onboarding and offboarding started and completed, last day; future-dated ones have scheduled true). Job details: the person, their managers (dotted-line ones too), owners, admins and HR, and custom roles covering them; others are refused. The person themselves never sees a planned last day or a future change here. Use it for "where is Ana in onboarding?" or "what is next for Ben?".

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

Input

  • person_idstringrequired

Returns

  • personobjectrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • todaystringrequired
  • stage"hired" | "onboarding" | "probation" | "employed" | "leaving" | "former"required

    null: never employed (an invited person with no job yet).

  • stagesobject[]required
    4 fields
    • key"hired" | "onboarding" | "probation" | "employed" | "leaving" | "former"required
    • state"done" | "current" | "upcoming" | "skipped"required
    • datestring | nullrequired

      hired: start date; probation: end date; leaving: last day; former: last day.

    • progressobject | nullrequired

      onboarding and leaving: the checklist progress.

      3 fields
      • doneintegerrequired
      • skippedintegerrequired
      • totalintegerrequired
  • nextobject | nullrequired
    4 fields
    • kind"start" | "onboarding_task" | "probation_end" | "contract_end" | "anniversary" | "last_day"required
    • datestring | nullrequired
    • labelstring | nullrequired

      onboarding_task: the task title.

    • tab"job" | "contract" | "checklists"required

      Where on the person page to act on it.

  • timelineobject[]required

    Newest first.

    10 fields
    • kindstring (enum)required

      One of: hired, rehired, promotion, transfer, change, pay, probation_ended, onboarding_started, onboarding_completed, offboarding_started, offboarding_completed, last_day.

    • datestringrequired
    • scheduledbooleanrequired

      A future-dated change (never shown to the person themselves).

    • titlestring | nullrequired
    • unitstring | nullrequired
    • managerstring | nullrequired
    • changedstring (enum)[]required

      One of: title, unit, manager, location, legal_entity, employment_type, fte, contract.

    • payobject | nullrequired
      3 fields
      • amountnumberrequired
      • currencystringrequired
      • periodstringrequired
    • checklistobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • tab"job" | "pay" | "contract" | "checklists"required

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/people.journey \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"person_id":"p1"}'
Response
{
  "data": {
    "person": {
      "id": "p2",
      "name": "Rui Costa",
      "title": "CTO",
      "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
    },
    "today": "2026-10-04",
    "stage": "probation",
    "stages": [
      {
        "key": "hired",
        "state": "done",
        "date": "2026-06-01",
        "progress": null
      },
      {
        "key": "onboarding",
        "state": "done",
        "date": null,
        "progress": {
          "done": 9,
          "skipped": 1,
          "total": 10
        }
      },
      {
        "key": "probation",
        "state": "current",
        "date": "2026-11-30",
        "progress": null
      },
      {
        "key": "employed",
        "state": "upcoming",
        "date": null,
        "progress": null
      },
      {
        "key": "leaving",
        "state": "upcoming",
        "date": null,
        "progress": null
      },
      {
        "key": "former",
        "state": "upcoming",
        "date": null,
        "progress": null
      }
    ],
    "next": {
      "kind": "probation_end",
      "date": "2026-11-30",
      "label": null,
      "tab": "contract"
    },
    "timeline": [
      {
        "kind": "onboarding_completed",
        "date": "2026-07-03",
        "scheduled": false,
        "title": null,
        "unit": null,
        "manager": null,
        "changed": [],
        "pay": null,
        "checklist": {
          "id": "run1",
          "name": "Onboarding"
        },
        "tab": "checklists"
      },
      {
        "kind": "hired",
        "date": "2026-06-01",
        "scheduled": false,
        "title": "Engineer",
        "unit": "Engineering",
        "manager": "Ana Ferreira",
        "changed": [],
        "pay": null,
        "checklist": null,
        "tab": "job"
      }
    ]
  }
}

People by journey stage#

POST/v1/org/people.journey_listRead

The people whose job details you may see (owners, admins and HR: everyone; a manager: the people below them; a custom role: those it covers), with their journey stage (hired, onboarding, probation, employed, leaving, former), the stage date (start date, probation end or last day; for onboarding, the next open task's due date) and checklist progress. stage filters to one stage; due_by (YYYY-MM-DD) keeps only those whose stage date is on or before it (e.g. probation ending this month). Former employees are listed only with stage "former". Never yourself. Use org_people_journey for one person's detail.

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

Input

  • stage"hired" | "onboarding" | "probation" | "employed" | "leaving" | "former"
  • due_bystring

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

Returns

  • todaystringrequired
  • peopleobject[]required
    4 fields
    • personobjectrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • stage"hired" | "onboarding" | "probation" | "employed" | "leaving" | "former"required
    • datestring | nullrequired
    • progressobject | nullrequired
      3 fields
      • doneintegerrequired
      • skippedintegerrequired
      • totalintegerrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/people.journey_list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stage":"probation","due_by":"2026-10-31"}'
Response
{
  "data": {
    "today": "2026-10-04",
    "people": [
      {
        "person": {
          "id": "p2",
          "name": "Rui Costa",
          "title": "CTO",
          "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
        },
        "stage": "probation",
        "date": "2026-11-30",
        "progress": null
      }
    ]
  }
}

Change a bank account (with proof)#

POST/v1/org/bank.requestWrite

With Verified bank details on: asks for a new bank account (IBAN) for yourself (person_id left out) or, as owner, admin, HR or a custom role with Private details at Edit, for someone else. Nothing changes for payroll yet: the change waits for a proof (org_bank_proof_start / org_bank_proof_finish), is checked automatically and, unless the company trusts the check, reviewed by HR. A new request replaces an open one. In the Bizisy app only (never over an API key or an AI app). validation_failed for an invalid IBAN; conflict when it is already the account on record. Part of the Verified bank details module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).

Web app only
Refused for API keys and connected apps. Bank accounts change in the app only (Verified bank details).
MCP tool
org_bank_request 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

  • person_idstring
  • ibanstringrequired

    15–42 characters.

Returns

13 fields
  • idstringrequired
  • personobjectrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • status"awaiting_proof" | "in_review" | "verified" | "rejected" | "cancelled"required
  • new_ibanstring | nullrequired

    The account asked for: only for the person and those who see private details; else null.

  • new_last4stringrequired
  • current_last4string | nullrequired

    The account payroll uses now (last 4 characters).

  • proofobject | nullrequired
    3 fields
    • content_typestringrequired
    • sizeintegerrequired
    • uploaded_atstringrequired
  • verdictobject | nullrequired
    3 fields
    • result"verified" | "needs_review" | "rejected"required
    • reasonsstring (enum)[]required

      One of: iban_on_document, iban_not_found, other_iban, name_matches, name_partial, name_not_found, unreadable, not_read, no_ai_credits.

    • checked_atstringrequired
  • requested_as"self" | "hr"required
  • decidedobject | nullrequired
    4 fields
    • how"automatic" | "hr"required
    • byobject | nullrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • atstringrequired
    • notestring | nullrequired
  • canobjectrequired
    3 fields
    • uploadbooleanrequired
    • decidebooleanrequired
    • cancelbooleanrequired
  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/bank.request \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"person_id":"p2"}'
Response
{
  "data": {
    "id": "bc1",
    "person": {
      "id": "p2",
      "name": "Rui Costa",
      "title": "CTO",
      "photo_url": null
    },
    "status": "awaiting_proof",
    "new_iban": "PT50000201231234567890154",
    "new_last4": "0154",
    "current_last4": "3000",
    "proof": null,
    "verdict": null,
    "requested_as": "self",
    "decided": null,
    "can": {
      "upload": true,
      "decide": true,
      "cancel": true
    },
    "created_at": "2026-10-04T10:00:00.000Z",
    "updated_at": "2026-10-04T10:01:02.000Z"
  }
}

Start uploading a bank proof#

POST/v1/org/bank.proof.startWrite

Starts the upload of the proof for a bank account change: a bank statement or the bank's IBAN certificate showing the account and its holder, as PDF, PNG, JPEG or WebP, at most 10 MB. Returns a signed upload (PUT the bytes within 15 minutes), then call org_bank_proof_finish. The person or HR, in the app only. Part of the Verified bank details module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).

Web app only
Refused for API keys and connected apps. Bank accounts change in the app only (Verified bank details).
MCP tool
org_bank_proof_start 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

  • change_idstringrequired
  • namestringrequired

    1–200 characters.

  • sizeintegerrequired

    At least 1.

  • content_typestringrequired
  • sha256stringrequired

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

Returns

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

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/bank.proof.start \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "change_id": "bc1",
  "name": "iban.pdf",
  "size": 48211,
  "content_type": "application/pdf",
  "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}'
Response
{
  "data": {
    "file_id": "f1",
    "upload": {
      "url": "https://storage.googleapis.com/upload",
      "method": "PUT",
      "headers": {
        "content-type": "application/pdf"
      },
      "resumable": false
    },
    "expires_at": "2026-10-04T10:15:00.000Z"
  }
}

Check a bank proof#

POST/v1/org/bank.proof.finishWrite

Finishes the proof upload and checks it automatically (Google Cloud Document AI reads the text; Bizisy looks for the IBAN and the holder's legal name). Checking a bank proof uses 1 AI credit (ai_credits says how many are left; a dry run says the cost and reads nothing); with no AI credits left the proof is not read and HR reviews it (reason no_ai_credits, which only HR sees). Verdict verified (applied at once when the company trusts the check, else HR reviews), needs_review (HR reviews) or rejected (a different account is on the document: upload another proof or cancel). The reasons say why; the document's text is never kept. At most 5 checks per person and 200 per company a day (rate_limited). The person or HR, in the app only. Part of the Verified bank details module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).

Web app only
Refused for API keys and connected apps. Bank accounts change in the app only (Verified bank details).
MCP tool
org_bank_proof_finish 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

  • change_idstringrequired
  • file_idstringrequired

Returns

14 fields
  • idstringrequired
  • personobjectrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • status"awaiting_proof" | "in_review" | "verified" | "rejected" | "cancelled"required
  • new_ibanstring | nullrequired

    The account asked for: only for the person and those who see private details; else null.

  • new_last4stringrequired
  • current_last4string | nullrequired

    The account payroll uses now (last 4 characters).

  • proofobject | nullrequired
    3 fields
    • content_typestringrequired
    • sizeintegerrequired
    • uploaded_atstringrequired
  • verdictobject | nullrequired
    3 fields
    • result"verified" | "needs_review" | "rejected"required
    • reasonsstring (enum)[]required

      One of: iban_on_document, iban_not_found, other_iban, name_matches, name_partial, name_not_found, unreadable, not_read, no_ai_credits.

    • checked_atstringrequired
  • requested_as"self" | "hr"required
  • decidedobject | nullrequired
    4 fields
    • how"automatic" | "hr"required
    • byobject | nullrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • atstringrequired
    • notestring | nullrequired
  • canobjectrequired
    3 fields
    • uploadbooleanrequired
    • decidebooleanrequired
    • cancelbooleanrequired
  • created_atstringrequired
  • updated_atstringrequired
  • ai_creditsobject | nullrequired

    For HR only (null for the person, and when Bizisy does not read proofs here): what checking the proof costs. A dry run says what it would use and reads nothing.

    3 fields
    • costintegerrequired

      AI credits a check uses (1).

    • leftinteger | nullrequired

      AI credits the company has left (after this check; on a dry run, now); null when unlimited.

    • notestringrequired

      The same in words, e.g. "Uses 1 AI credit (12 left)".

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/bank.proof.finish \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"change_id":"bc1","file_id":"f1"}'
Response
{
  "data": {
    "id": "bc1",
    "person": {
      "id": "p2",
      "name": "Rui Costa",
      "title": "CTO",
      "photo_url": null
    },
    "status": "in_review",
    "new_iban": "PT50000201231234567890154",
    "new_last4": "0154",
    "current_last4": "3000",
    "proof": {
      "content_type": "application/pdf",
      "size": 48211,
      "uploaded_at": "2026-10-04T10:01:00.000Z"
    },
    "verdict": {
      "result": "verified",
      "reasons": [
        "iban_on_document",
        "name_matches"
      ],
      "checked_at": "2026-10-04T10:01:02.000Z"
    },
    "requested_as": "self",
    "decided": null,
    "can": {
      "upload": true,
      "decide": true,
      "cancel": true
    },
    "created_at": "2026-10-04T10:00:00.000Z",
    "updated_at": "2026-10-04T10:01:02.000Z",
    "ai_credits": {
      "cost": 1,
      "left": 12,
      "note": "Used 1 AI credit (12 left)"
    }
  }
}

Approve or reject a bank account change#

POST/v1/org/bank.decideWrite

HR decides a bank account change waiting for review (status in_review), after looking at the proof (org_bank_proof_url) and the automatic verdict: approve sets the account for payroll (the person and HR get the usual payroll details email), reject closes it (note: why, shown to the person). Owners, admins, HR and custom roles with Private details at Edit covering the person; never your own change, and never one you asked for (a second person decides). In the app only. Part of the Verified bank details module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).

Web app only
Refused for API keys and connected apps. Bank accounts change in the app only (Verified bank details).
MCP tool
org_bank_decide 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

  • change_idstringrequired
  • decision"approve" | "reject"required
  • notestring

    Up to 300 characters.

  • proof_uploaded_atstring

    The proof's uploaded_at as you read it: refused (conflict) when a newer proof came since.

Returns

13 fields
  • idstringrequired
  • personobjectrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • status"awaiting_proof" | "in_review" | "verified" | "rejected" | "cancelled"required
  • new_ibanstring | nullrequired

    The account asked for: only for the person and those who see private details; else null.

  • new_last4stringrequired
  • current_last4string | nullrequired

    The account payroll uses now (last 4 characters).

  • proofobject | nullrequired
    3 fields
    • content_typestringrequired
    • sizeintegerrequired
    • uploaded_atstringrequired
  • verdictobject | nullrequired
    3 fields
    • result"verified" | "needs_review" | "rejected"required
    • reasonsstring (enum)[]required

      One of: iban_on_document, iban_not_found, other_iban, name_matches, name_partial, name_not_found, unreadable, not_read, no_ai_credits.

    • checked_atstringrequired
  • requested_as"self" | "hr"required
  • decidedobject | nullrequired
    4 fields
    • how"automatic" | "hr"required
    • byobject | nullrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • atstringrequired
    • notestring | nullrequired
  • canobjectrequired
    3 fields
    • uploadbooleanrequired
    • decidebooleanrequired
    • cancelbooleanrequired
  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/bank.decide \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "change_id": "bc1",
  "decision": "reject",
  "note": "The holder is someone else"
}'
Response
{
  "data": {
    "id": "bc1",
    "person": {
      "id": "p2",
      "name": "Rui Costa",
      "title": "CTO",
      "photo_url": null
    },
    "status": "verified",
    "new_iban": "PT50000201231234567890154",
    "new_last4": "0154",
    "current_last4": "3000",
    "proof": {
      "content_type": "application/pdf",
      "size": 48211,
      "uploaded_at": "2026-10-04T10:01:00.000Z"
    },
    "verdict": {
      "result": "verified",
      "reasons": [
        "iban_on_document",
        "name_matches"
      ],
      "checked_at": "2026-10-04T10:01:02.000Z"
    },
    "requested_as": "self",
    "decided": {
      "how": "hr",
      "by": {
        "id": "p2",
        "name": "Rui Costa",
        "title": "CTO",
        "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
      },
      "at": "2026-10-04T11:00:00.000Z",
      "note": null
    },
    "can": {
      "upload": false,
      "decide": false,
      "cancel": false
    },
    "created_at": "2026-10-04T10:00:00.000Z",
    "updated_at": "2026-10-04T10:01:02.000Z"
  }
}

Cancel a bank account change#

POST/v1/org/bank.cancelWrite

Cancels an open bank account change (waiting for a proof or for review); the account on record stays and the proof is deleted. The person or HR, in the app only. Part of the Verified bank details module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).

Web app only
Refused for API keys and connected apps. Bank accounts change in the app only (Verified bank details).
MCP tool
org_bank_cancel 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

  • change_idstringrequired

Returns

13 fields
  • idstringrequired
  • personobjectrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • status"awaiting_proof" | "in_review" | "verified" | "rejected" | "cancelled"required
  • new_ibanstring | nullrequired

    The account asked for: only for the person and those who see private details; else null.

  • new_last4stringrequired
  • current_last4string | nullrequired

    The account payroll uses now (last 4 characters).

  • proofobject | nullrequired
    3 fields
    • content_typestringrequired
    • sizeintegerrequired
    • uploaded_atstringrequired
  • verdictobject | nullrequired
    3 fields
    • result"verified" | "needs_review" | "rejected"required
    • reasonsstring (enum)[]required

      One of: iban_on_document, iban_not_found, other_iban, name_matches, name_partial, name_not_found, unreadable, not_read, no_ai_credits.

    • checked_atstringrequired
  • requested_as"self" | "hr"required
  • decidedobject | nullrequired
    4 fields
    • how"automatic" | "hr"required
    • byobject | nullrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • atstringrequired
    • notestring | nullrequired
  • canobjectrequired
    3 fields
    • uploadbooleanrequired
    • decidebooleanrequired
    • cancelbooleanrequired
  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/bank.cancel \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"change_id":"bc1"}'
Response
{
  "data": {
    "id": "bc1",
    "person": {
      "id": "p2",
      "name": "Rui Costa",
      "title": "CTO",
      "photo_url": null
    },
    "status": "cancelled",
    "new_iban": "PT50000201231234567890154",
    "new_last4": "0154",
    "current_last4": "3000",
    "proof": null,
    "verdict": {
      "result": "verified",
      "reasons": [
        "iban_on_document",
        "name_matches"
      ],
      "checked_at": "2026-10-04T10:01:02.000Z"
    },
    "requested_as": "self",
    "decided": null,
    "can": {
      "upload": false,
      "decide": false,
      "cancel": false
    },
    "created_at": "2026-10-04T10:00:00.000Z",
    "updated_at": "2026-10-04T10:01:02.000Z"
  }
}

Get a bank account change#

POST/v1/org/bank.getRead

One bank account change: status, the account asked for (only for the person and those who see private details), the proof's type and size, the automatic verdict and its reasons, and who decided. The person or HR, in the app only. Part of the Verified bank details module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules); this read of stored data keeps working while it is off.

Web app only
Refused for API keys and connected apps. Bank accounts change in the app only (Verified bank details).
MCP tool
org_bank_get on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • change_idstringrequired

Returns

13 fields
  • idstringrequired
  • personobjectrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • status"awaiting_proof" | "in_review" | "verified" | "rejected" | "cancelled"required
  • new_ibanstring | nullrequired

    The account asked for: only for the person and those who see private details; else null.

  • new_last4stringrequired
  • current_last4string | nullrequired

    The account payroll uses now (last 4 characters).

  • proofobject | nullrequired
    3 fields
    • content_typestringrequired
    • sizeintegerrequired
    • uploaded_atstringrequired
  • verdictobject | nullrequired
    3 fields
    • result"verified" | "needs_review" | "rejected"required
    • reasonsstring (enum)[]required

      One of: iban_on_document, iban_not_found, other_iban, name_matches, name_partial, name_not_found, unreadable, not_read, no_ai_credits.

    • checked_atstringrequired
  • requested_as"self" | "hr"required
  • decidedobject | nullrequired
    4 fields
    • how"automatic" | "hr"required
    • byobject | nullrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • atstringrequired
    • notestring | nullrequired
  • canobjectrequired
    3 fields
    • uploadbooleanrequired
    • decidebooleanrequired
    • cancelbooleanrequired
  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/bank.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"change_id":"bc1"}'
Response
{
  "data": {
    "id": "bc1",
    "person": {
      "id": "p2",
      "name": "Rui Costa",
      "title": "CTO",
      "photo_url": null
    },
    "status": "in_review",
    "new_iban": "PT50000201231234567890154",
    "new_last4": "0154",
    "current_last4": "3000",
    "proof": {
      "content_type": "application/pdf",
      "size": 48211,
      "uploaded_at": "2026-10-04T10:01:00.000Z"
    },
    "verdict": {
      "result": "verified",
      "reasons": [
        "iban_on_document",
        "name_matches"
      ],
      "checked_at": "2026-10-04T10:01:02.000Z"
    },
    "requested_as": "self",
    "decided": null,
    "can": {
      "upload": true,
      "decide": true,
      "cancel": true
    },
    "created_at": "2026-10-04T10:00:00.000Z",
    "updated_at": "2026-10-04T10:01:02.000Z"
  }
}

My bank account change#

POST/v1/org/bank.mineRead

Your latest bank account change, if any (open, or closed in the last 30 days), and whether changes need a proof (the company has Verified bank details).

Who can call it
Me key anyone
MCP tool
org_bank_mine on My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • requiredbooleanrequired
  • changeobject | nullrequired
    13 fields
    • idstringrequired
    • personobjectrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • status"awaiting_proof" | "in_review" | "verified" | "rejected" | "cancelled"required
    • new_ibanstring | nullrequired

      The account asked for: only for the person and those who see private details; else null.

    • new_last4stringrequired
    • current_last4string | nullrequired

      The account payroll uses now (last 4 characters).

    • proofobject | nullrequired
      3 fields
      • content_typestringrequired
      • sizeintegerrequired
      • uploaded_atstringrequired
    • verdictobject | nullrequired
      3 fields
      • result"verified" | "needs_review" | "rejected"required
      • reasonsstring (enum)[]required

        One of: iban_on_document, iban_not_found, other_iban, name_matches, name_partial, name_not_found, unreadable, not_read, no_ai_credits.

      • checked_atstringrequired
    • requested_as"self" | "hr"required
    • decidedobject | nullrequired
      4 fields
      • how"automatic" | "hr"required
      • byobject | nullrequired
        4 fields
        • idstringrequired
        • namestringrequired
        • titlestring | nullrequired
        • photo_urlstring | nullrequired
      • atstringrequired
      • notestring | nullrequired
    • canobjectrequired
      3 fields
      • uploadbooleanrequired
      • decidebooleanrequired
      • cancelbooleanrequired
    • created_atstringrequired
    • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/bank.mine \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "required": true,
    "change": {
      "id": "bc1",
      "person": {
        "id": "p2",
        "name": "Rui Costa",
        "title": "CTO",
        "photo_url": null
      },
      "status": "in_review",
      "new_iban": "PT50000201231234567890154",
      "new_last4": "0154",
      "current_last4": "3000",
      "proof": {
        "content_type": "application/pdf",
        "size": 48211,
        "uploaded_at": "2026-10-04T10:01:00.000Z"
      },
      "verdict": {
        "result": "verified",
        "reasons": [
          "iban_on_document",
          "name_matches"
        ],
        "checked_at": "2026-10-04T10:01:02.000Z"
      },
      "requested_as": "self",
      "decided": null,
      "can": {
        "upload": true,
        "decide": true,
        "cancel": true
      },
      "created_at": "2026-10-04T10:00:00.000Z",
      "updated_at": "2026-10-04T10:01:02.000Z"
    }
  }
}

List bank account changes#

POST/v1/org/bank.changes.listRead

Bank account changes HR may see: status open (default: waiting for a proof or for review), in_review, or all (the last 100). person_id narrows to one person. Owners, admins, HR and custom roles with Private details at Edit (the people they cover), in the app only. Part of the Verified bank details module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules); this read of stored data keeps working while it is off.

Web app only
Refused for API keys and connected apps. Bank accounts change in the app only (Verified bank details).
MCP tool
org_bank_changes_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • status"open" | "in_review" | "all"

    Default "open".

  • person_idstring

Returns

  • changesobject[]required
    13 fields
    • idstringrequired
    • personobjectrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • status"awaiting_proof" | "in_review" | "verified" | "rejected" | "cancelled"required
    • new_ibanstring | nullrequired

      The account asked for: only for the person and those who see private details; else null.

    • new_last4stringrequired
    • current_last4string | nullrequired

      The account payroll uses now (last 4 characters).

    • proofobject | nullrequired
      3 fields
      • content_typestringrequired
      • sizeintegerrequired
      • uploaded_atstringrequired
    • verdictobject | nullrequired
      3 fields
      • result"verified" | "needs_review" | "rejected"required
      • reasonsstring (enum)[]required

        One of: iban_on_document, iban_not_found, other_iban, name_matches, name_partial, name_not_found, unreadable, not_read, no_ai_credits.

      • checked_atstringrequired
    • requested_as"self" | "hr"required
    • decidedobject | nullrequired
      4 fields
      • how"automatic" | "hr"required
      • byobject | nullrequired
        4 fields
        • idstringrequired
        • namestringrequired
        • titlestring | nullrequired
        • photo_urlstring | nullrequired
      • atstringrequired
      • notestring | nullrequired
    • canobjectrequired
      3 fields
      • uploadbooleanrequired
      • decidebooleanrequired
      • cancelbooleanrequired
    • created_atstringrequired
    • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/bank.changes.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"all","person_id":"p2"}'
Response
{
  "data": {
    "changes": [
      {
        "id": "bc1",
        "person": {
          "id": "p2",
          "name": "Rui Costa",
          "title": "CTO",
          "photo_url": null
        },
        "status": "in_review",
        "new_iban": "PT50000201231234567890154",
        "new_last4": "0154",
        "current_last4": "3000",
        "proof": {
          "content_type": "application/pdf",
          "size": 48211,
          "uploaded_at": "2026-10-04T10:01:00.000Z"
        },
        "verdict": {
          "result": "verified",
          "reasons": [
            "iban_on_document",
            "name_matches"
          ],
          "checked_at": "2026-10-04T10:01:02.000Z"
        },
        "requested_as": "self",
        "decided": null,
        "can": {
          "upload": true,
          "decide": true,
          "cancel": true
        },
        "created_at": "2026-10-04T10:00:00.000Z",
        "updated_at": "2026-10-04T10:01:02.000Z"
      }
    ]
  }
}

Open a bank proof#

POST/v1/org/bank.proof_urlRead

A link (5 minutes) to download the proof of a bank account change. The person or HR, in the app only. Part of the Verified bank details module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules); this read of stored data keeps working while it is off.

Web app only
Refused for API keys and connected apps. Bank accounts change in the app only (Verified bank details).
MCP tool
org_bank_proof_url on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • change_idstringrequired

Returns

  • urlstringrequired
  • expires_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/bank.proof_url \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"change_id":"bc1"}'
Response
{
  "data": {
    "url": "https://storage.googleapis.com/download",
    "expires_at": "2026-10-04T10:05:00.000Z"
  }
}

Get the bank details settings#

POST/v1/org/bank.settings.getRead

Verified bank details: whether a change the automatic check verified applies at once (trust_automatic true) or HR always reviews it (false, the default). Owners, admins and HR, in the app only. Part of the Verified bank details module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules); this read of stored data keeps working while it is off.

Web app only
Refused for API keys and connected apps. Bank accounts change in the app only (Verified bank details).
MCP tool
org_bank_settings_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • trust_automaticbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/bank.settings.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "trust_automatic": false
  }
}

Change the bank details settings#

POST/v1/org/bank.settings.updateWrite

trust_automatic: true applies a change the automatic check verified at once (needs-review and rejected ones still go to HR or back to the person); false (the default) has HR review every change. Owners and admins, in the app only. Part of the Verified bank details module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).

Web app only
Refused for API keys and connected apps. Bank accounts change in the app only (Verified bank details).
MCP tool
org_bank_settings_update on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • trust_automaticbooleanrequired

Returns

  • trust_automaticbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/bank.settings.update \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"trust_automatic":true}'
Response
{
  "data": {
    "trust_automatic": true
  }
}

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

Developer docs