Skip to content

API reference

Jobs and employment

Hire (with starting pay and a scheduled invite), change jobs from a date, terminate (and say whether the person has been told), rehire, correct job history, and save any of it for later.

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

Hire (add) a person#

POST/v1/org/people.hireWrite

Adds a person with their first job. Required: given_name, family_name, work_email (unique), title (as typed: matched to the job title catalog, else added to it; title_match in the result says which, with similar titles) or title_id (from org_titles_list), start_date (YYYY-MM-DD; a future date makes them pre_hire). Optional: unit_id, manager_id (must be employed or starting on start_date; when absent and unit_id is set, the team lead of that unit becomes the manager — manager_default in the result says so; send null for no manager; a position_id whose position names whom it reports to gets no default), location_id and legal_entity_id (default to the only active one), employment_type (full_time, part_time, contractor, intern; default full_time), fte (0–1, default 1), contract terms (contract_type: permanent, fixed_term, temporary, internship, freelance; contract_end_date for fixed_term/temporary/internship; probation_end_date; weekly_hours; notice_period_days), profile fields (including tax_id, social_security_number, iban and sex: refused over an API key or MCP) and custom: { <field key>: value } (see org_fields_list), position_id (an open or on-hold position from org_positions_list: the hire fills it, and positions that reported to it then report to the new person; drafts, filled and cancelled positions are refused). Starts the onboarding checklists that start by themselves and match the person (see org_checklists_runs_list), unless the start date is more than 30 days ago (onboarding in the result counts them and their tasks). pay: optional starting pay {amount, currency, period, note} from start_date, with org_pay_add's rules (in the app only; refused over MCP or an API key; becomes a request when pay changes need approval). invite: {when: now | start | days_before | none, days (1–14, with days_before), role}: the sign-in invite now, or at 08:00 company time on that day (org_invites_scheduled lists them). source {kind: hiring, job_id, application_id} (from hiring_applications_hire_draft, in the app only): the candidate becomes hired and linked to the person, and their referral is recorded. Use dry_run first.

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_hire 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_namestringrequired

    1–100 characters.

  • family_namestringrequired

    1–100 characters.

  • work_emailanyrequired
  • 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 }].

  • 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.

  • unit_idstring | null
  • manager_idstring | null
  • location_idstring | null
  • legal_entity_idstring | null
  • employment_type"full_time" | "part_time" | "contractor" | "intern"

    Default "full_time".

  • ftenumber

    From 0 to 1. Default 1.

  • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"
  • contract_end_datestring | null
  • probation_end_datestring | null
  • weekly_hoursnumber | null

    From 0 to 80.

  • notice_period_daysinteger | null

    From 0 to 365.

  • start_datestringrequired
  • position_idstring
  • payobject

    Starting pay from start_date (in the app only, like org_pay_add; a request when pay changes need approval).

    4 fields
    • amountnumberrequired

      From 0 to 100000000.

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

      Up to 200 characters.

  • inviteobject

    The sign-in invite: now, on their first day (start), days_before (1–14 days before the start) or none (default). A day today or earlier sends it at once.

    3 fields
    • when"now" | "start" | "days_before" | "none"required
    • daysinteger

      From 1 to 14.

    • role"member" | "hr" | "admin" | "viewer"
  • sourceobject

    A candidate hired from Hiring (hiring_applications_hire_draft gives it): the candidate becomes hired and linked to this person, in the same change. In the app only.

    3 fields
    • kind"hiring"required
    • job_idstringrequired
    • application_idstringrequired

Returns

40 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
  • manager_defaultobject | nullrequired

    The manager was not given, so the lead of this team became the manager (null: the manager was given, or there was no default).

    2 fields
    • unit_idstringrequired
    • unit_namestringrequired
  • 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.

  • payobject | nullrequired

    The starting pay: recorded, or a request waiting for approval.

    2 fields
    • recordedbooleanrequired
    • 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
  • inviteobject | nullrequired
    5 fields
    • status"sent" | "scheduled"required
    • onstringrequired

      The company-local day it was or will be sent.

    • urlstring | nullrequired

      The sign-in link, only when sent now and only in the web app.

    • expires_atstring | nullrequired
    • emailobject | nullrequired
      3 fields
      • status"sent" | "failed" | "skipped"required
      • messagestringrequired
      • reason"rate_limited"
  • onboardingobjectrequired

    Onboarding checklists started for them, and their tasks.

    2 fields
    • checklistsintegerrequired
    • tasksintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/people.hire \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "given_name": "Inês",
  "family_name": "Martins",
  "preferred_name": "Inês M.",
  "work_email": "ines@acme.test",
  "work_phone": "+351 912 000 000",
  "personal_email": "ines@example.test",
  "personal_phone": null,
  "address": {
    "line1": "Rua A 1",
    "line2": "2 Esq",
    "city": "Porto",
    "postal_code": "4000-001",
    "country": "PT"
  },
  "birthday": "1995-02-01",
  "pronouns": "she/her",
  "emergency_contacts": [
    {
      "name": "Rui",
      "relationship": "Partner",
      "phone": "+351 911"
    }
  ],
  "title": "AE",
  "unit_id": "u2",
  "manager_id": "p2",
  "location_id": null,
  "legal_entity_id": null,
  "employment_type": "contractor",
  "fte": 0.5,
  "start_date": "2026-11-02"
}'
Response
{
  "data": {
    "id": "p1",
    "name": "Inês M.",
    "given_name": "Inês",
    "family_name": "Martins",
    "preferred_name": "Inês M.",
    "work_email": "ines@acme.test",
    "title": "AE",
    "status": "active",
    "start_date": "2026-11-02",
    "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 912 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": "AE",
      "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": [],
    "manager_default": {
      "unit_id": "u2",
      "unit_name": "Engineering"
    },
    "title_match": {
      "id": null,
      "name": "Backend Engineer",
      "created": true,
      "similar": [
        {
          "id": "t1",
          "name": "Back-end Engineer",
          "people": 6
        }
      ]
    },
    "pay": {
      "recorded": true,
      "approval": null
    },
    "invite": {
      "status": "scheduled",
      "on": "2026-11-02",
      "url": null,
      "expires_at": null,
      "email": null
    },
    "onboarding": {
      "checklists": 1,
      "tasks": 6
    }
  }
}

Change a person's job (effective-dated)#

POST/v1/org/people.change_jobWrite

Records a job change from effective_date (YYYY-MM-DD, may be in the future): title, unit_id, manager_id, location_id, legal_entity_id, employment_type, fte and/or contract terms (contract_type, contract_end_date, probation_end_date, weekly_hours, notice_period_days; null clears one), and custom: job custom fields (org_fields_list, target job; { <key>: value }, null clears one; the others carry forward). title is matched to the job title catalog or added to it when the change applies (title_match in the result says which, with similar titles); or send title_id. display_title shows a different title on the profile. reason is change, promotion or transfer. Moving into another unit without manager_id makes that unit's team lead the manager (the parent unit's lead when the person is that lead; manager_default in the result says so); send manager_id (or null) to choose. When Settings → Approval rules requires approval for job changes, nothing changes yet: a request is created for the approvers (approval in the result says who; org_approvals_get follows it) and the change applies when approved; a person can have one open job request at a time. The current row is closed on that date and a new one opens with the merged fields; a scheduled termination is kept. Rejected if the person is not employed that day, if a row already starts that day (use org_people_correct_job), if the manager is not employed then, or if it would create a reporting cycle on any day from effective_date on. Rows already scheduled after effective_date keep their own values — check history if a later change exists. If every field sent already has that value on effective_date, nothing is written and unchanged is true (safe to retry).

Who can call it
Manage key owner admin hr
MCP tool
org_people_change_job on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • titlestring

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

    1–120 characters.

  • title_idstring

    A job title from org_titles_list, instead of title.

  • 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.

  • unit_idstring | null
  • manager_idstring | null
  • location_idstring | null
  • legal_entity_idstring | null
  • employment_type"full_time" | "part_time" | "contractor" | "intern"
  • ftenumber

    From 0 to 1.

  • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"
  • contract_end_datestring | null
  • probation_end_datestring | null
  • weekly_hoursnumber | null

    From 0 to 80.

  • notice_period_daysinteger | null

    From 0 to 365.

  • customobject

    Job custom fields (org_fields_list, target job) by key; null clears one. Values follow the job timeline: the others carry forward unchanged.

  • person_idstringrequired
  • effective_datestringrequired
  • reason"change" | "promotion" | "transfer"required

Returns

39 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
  • unchangedboolean

    true when the job already was exactly so on effective_date: nothing was written.

  • manager_defaultobject | nullrequired

    The manager was not given, so the lead of this team became the manager (null: the manager was given, or there was no default).

    2 fields
    • unit_idstringrequired
    • unit_namestringrequired
  • 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.change_job \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "person_id": "p1",
  "effective_date": "2026-10-05",
  "reason": "transfer",
  "unit_id": "u3",
  "manager_id": null,
  "location_id": "l2",
  "legal_entity_id": "e1",
  "employment_type": "part_time",
  "fte": 0.8
}'
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": [],
    "approval": {
      "id": "apr1",
      "status": "pending",
      "waiting_for": "manager",
      "approvers": [
        "Bea Silva"
      ],
      "automatic": false,
      "note": null,
      "fallback": false,
      "then": "hr",
      "team_lead": {
        "unit_id": "u2",
        "unit_name": "Engineering",
        "reason": "no_manager"
      },
      "team_lead_blocked": null,
      "untrusted": null
    },
    "manager_default": null,
    "title_match": {
      "id": "t1",
      "name": "Back-end Engineer",
      "created": false,
      "matched_from": "backend engineer"
    }
  }
}

Terminate employment#

POST/v1/org/people.terminateDestructive

Prefer org_people_mark_leaving, which also reassigns direct reports, can open a replacement position and ends the login. Ends employment after last_day (inclusive, YYYY-MM-DD, may be in the future) and starts the offboarding checklists that start by themselves (see org_checklists_runs_list); reason is free text (e.g. resigned; default: the reason of a scheduled termination it replaces, else "terminated"); leaving_type is why, structured (resignation, retirement, dismissal, redundancy, end_of_contract, mutual_agreement, death, other), for the turnover split in Reports. Job changes scheduled after the last day are removed, and a later scheduled termination is moved to last_day. If this employment period already has an end date, use org_people_correct_job (valid_to = last day + 1) instead. Direct reports are NOT reassigned: warnings lists them so you can change their manager. If they have a login, warnings says so: it keeps working until an owner or admin disables it with platform_members_disable. When Settings → Approval rules requires approval for terminations, a request is created instead (approval in the result): the termination, and its offboarding checklists, start only when it is approved.

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

  • 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
  • warningsstring[]required
  • 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

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/people.terminate \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"person_id":"p1","last_day":"2026-10-31","reason":"resigned"}'
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": []
    },
    "warnings": [
      "Ana Ferreira can still sign in until an owner or admin disables their login."
    ],
    "approval": null
  }
}

Rehire a former employee#

POST/v1/org/people.rehireWrite

Starts a new employment for someone who has left, from start_date, with a new title and optional unit_id, manager_id (absent with a unit_id: that unit's team lead, as manager_default says; null for none), location_id, legal_entity_id, employment_type (default full_time) and fte (default 1). Rejected while they are still employed on start_date, if they already have a later job, or if they were never terminated (use org_people_hire for new people). When Settings → Approval rules requires approval for job changes, a request is created instead (approval in the result) and the rehire applies when approved.

Who can call it
Manage key owner admin hr
MCP tool
org_people_rehire on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • titlestring

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

    1–120 characters.

  • title_idstring

    A job title from org_titles_list, instead of title.

  • 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.

  • unit_idstring | null
  • manager_idstring | null
  • location_idstring | null
  • legal_entity_idstring | null
  • employment_type"full_time" | "part_time" | "contractor" | "intern"

    Default "full_time".

  • ftenumber

    From 0 to 1. Default 1.

  • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"
  • contract_end_datestring | null
  • probation_end_datestring | null
  • weekly_hoursnumber | null

    From 0 to 80.

  • notice_period_daysinteger | null

    From 0 to 365.

  • customobject

    Job custom fields (org_fields_list, target job) by key; null clears one. Values follow the job timeline: the others carry forward unchanged.

  • person_idstringrequired
  • start_datestringrequired

Returns

38 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
  • manager_defaultobject | nullrequired

    The manager was not given, so the lead of this team became the manager (null: the manager was given, or there was no default).

    2 fields
    • unit_idstringrequired
    • unit_namestringrequired
  • 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.rehire \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "person_id": "p1",
  "start_date": "2026-11-02",
  "title": "Engineer",
  "unit_id": "u2",
  "manager_id": "p2",
  "location_id": null,
  "legal_entity_id": "e1",
  "employment_type": "intern",
  "fte": 1
}'
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": "2026-11-02",
    "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,
    "manager_default": null,
    "title_match": null
  }
}

Correct a job row (fix history)#

POST/v1/org/people.correct_jobWrite

Fixes a mistake in one job row in place, without recording a new change: title, unit_id, manager_id, location_id, legal_entity_id, employment_type, fte, or valid_from (a contiguous previous row is adjusted with it). On the last row of an employment period that already has an end date, last_day (inclusive; or valid_to, the day after it) and end_reason or leaving_type adjust the termination: a later valid_to postpones it, an earlier one moves it earlier within that row (to end before a scheduled change, use org_people_terminate), and valid_to = null cancels it. It never ends an open-ended row: use org_people_terminate for that. Use it for typos and wrong dates, not for real changes (use org_people_change_job). Open checklist tasks move with a corrected start date or last day, and cancelling a termination cancels its offboarding checklist. Every correction is audited. When Settings → Approval rules requires approval, a correction of the current or a future row (job changes), or of a last day (terminations), creates a request instead (approval in the result), and checklists move only when it is approved; corrections of rows that ended before today apply at once.

Who can call it
Manage key owner admin hr
MCP tool
org_people_correct_job on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • titlestring

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

    1–120 characters.

  • title_idstring

    A job title from org_titles_list, instead of title.

  • 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.

  • unit_idstring | null
  • manager_idstring | null
  • location_idstring | null
  • legal_entity_idstring | null
  • employment_type"full_time" | "part_time" | "contractor" | "intern"
  • ftenumber

    From 0 to 1.

  • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"
  • contract_end_datestring | null
  • probation_end_datestring | null
  • weekly_hoursnumber | null

    From 0 to 80.

  • notice_period_daysinteger | null

    From 0 to 365.

  • customobject

    Job custom fields (org_fields_list, target job) by key; null clears one. Values follow the job timeline: the others carry forward unchanged.

  • job_idstringrequired
  • valid_fromstring
  • valid_tostring | null
  • last_daystring

    The last day worked (inclusive), as org_people_terminate takes it: the same as valid_to = last_day + 1. Send last_day or valid_to, not both.

  • end_reasonstring | null

    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.

  • 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

37 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
  • 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.correct_job \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "job_id": "j1",
  "valid_from": "2024-01-16",
  "valid_to": null,
  "end_reason": null,
  "unit_id": null,
  "fte": 0.9
}'
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": [],
    "approval": {
      "id": "apr2",
      "status": "pending",
      "waiting_for": "hr",
      "approvers": [
        "Ana Ferreira"
      ],
      "automatic": false,
      "note": null,
      "fallback": false,
      "then": null,
      "team_lead": null,
      "team_lead_blocked": null,
      "untrusted": null
    },
    "title_match": null
  }
}

Dotted-line managers#

POST/v1/org/dotted_lines.listRead

Dotted-line (matrix) reporting lines: a secondary manager a person also works with, who sees their job details but never approves or proposes for them. Filter by person_id (their dotted-line managers) or manager_id (whom they have a dotted line to); ended lines are left out unless include_ended. The note is shown to those who see the person's job details.

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

Input

  • person_idstring
  • manager_idstring
  • include_endedboolean

    Default false.

Returns

An array of objects:

  • idstringrequired
  • personobjectrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • managerobjectrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • valid_fromstringrequired
  • last_daystring | nullrequired

    The last day (inclusive); null: open-ended.

  • notestring | nullrequired

    Job tier: only for those who see the person's job details.

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/dotted_lines.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"manager_id":"p7","include_ended":true}'
Response
{
  "data": [
    {
      "id": "dl1",
      "person": {
        "id": "p1",
        "name": "Ana Ferreira",
        "title": "Engineer",
        "photo_url": null
      },
      "manager": {
        "id": "p7",
        "name": "João Pereira",
        "title": "Sales Lead",
        "photo_url": null
      },
      "valid_from": "2026-10-04",
      "last_day": null,
      "note": "Platform project"
    }
  ]
}

Add a dotted-line manager#

POST/v1/org/dotted_lines.addWrite

Adds a dotted-line (matrix) manager for a person: someone they also work with and report to on a project or function, besides their manager. From valid_from (default today; YYYY-MM-DD) to last_day (inclusive, optional), with an optional note. The dotted-line manager sees the person's job details (not private details or pay), never approves or proposes changes for them, and shows on the chart, the person's page and their My team. At most 3 at a time; not their manager or themself; the dotted-line manager must work here on valid_from. Owners, admins and HR, and roles that edit the people they cover.

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

Input

  • person_idstringrequired
  • manager_idstringrequired
  • valid_fromstring
  • last_daystring
  • notestring

    1–300 characters.

Returns

  • idstringrequired
  • personobjectrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • managerobjectrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • valid_fromstringrequired
  • last_daystring | nullrequired

    The last day (inclusive); null: open-ended.

  • notestring | nullrequired

    Job tier: only for those who see the person's job details.

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/dotted_lines.add \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "person_id": "p1",
  "manager_id": "p7",
  "valid_from": "2026-10-04",
  "last_day": "2026-12-31",
  "note": "Platform project"
}'
Response
{
  "data": {
    "id": "dl1",
    "person": {
      "id": "p1",
      "name": "Ana Ferreira",
      "title": "Engineer",
      "photo_url": null
    },
    "manager": {
      "id": "p7",
      "name": "João Pereira",
      "title": "Sales Lead",
      "photo_url": null
    },
    "valid_from": "2026-10-04",
    "last_day": "2026-12-31",
    "note": "Platform project"
  }
}

End a dotted-line manager#

POST/v1/org/dotted_lines.endWrite

Ends a dotted-line reporting line after last_day (inclusive; default today). A line that has not started by then is removed. Owners, admins and HR, and roles that edit the people they cover.

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

Input

  • line_idstringrequired
  • last_daystring

Returns

  • idstringrequired
  • removedbooleanrequired
  • last_daystring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/dotted_lines.end \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"line_id":"dl1","last_day":"2026-12-31"}'
Response
{
  "data": {
    "id": "dl1",
    "removed": false,
    "last_day": "2026-12-31"
  }
}

Mark someone as told about their last day#

POST/v1/org/people.mark_toldWrite

Records that a person has been told about their last day. A termination recorded with person_told false (the default for dismissals, redundancies, contracts not renewed, other and unrecorded leaving types) is kept from the person: they don't see the last day, why they leave, their offboarding tasks or the effect on their time off until they are marked told or the day passes. Marking them told shows them everything, starts their offboarding tasks and ends their time off booked after the last day. Owners, admins and HR, a custom role with People at Propose or more covering them, or anyone in their management chain; never about yourself. Already told: nothing changes (changed false). conflict when they have no last day ahead.

Who can call it
Manage key any Manage role
Me key anyone
MCP tool
org_people_mark_told 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

Returns

  • personobjectrequired
    4 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • photo_urlstring | nullrequired
  • last_daystringrequired
  • changedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/people.mark_told \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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"
    },
    "last_day": "2026-11-30",
    "changed": true
  }
}

Save a process for later#

POST/v1/org/drafts.saveWrite

Saves a process about people that is not finished yet, so anyone who may start it can carry on later in Bizisy (People → Saved for later) or through this API. process: hire, change_job, promote, move, leaving, probation, contract or rehire; person_ids: the person (none for a hire; one or more for a move); label: a short name shown in the list (e.g. "Ana Lima · Engineer"); data.input: the action's input as far as it is known, with the same field names (org_people_hire, org_people_change_job, org_people_promote, org_people_move, org_people_mark_leaving, org_people_contract_decide, org_people_rehire), so the web app opens it in that process's form. A process about one person keeps one saved draft per person (saving again replaces it); hires and moves keep many (draft_id replaces one). Kept until someone deletes it. Over an API key or MCP, private details and pay are refused (the person adds them in the app). Owners, admins and HR, and custom roles for the people they cover. In My workspace, a manager saves a proposal for someone in their team: process proposal, variant promote, move, resign or probation, data.input the proposal so far (org_people_promote, org_people_move, org_people_mark_leaving or org_people_probation_decide); it is private to them (HR sees it once sent), one per person and variant, at most ${MAX_PROPOSAL_DRAFTS}.

Who can call it
Manage key any Manage role
Me key anyone
Keys and apps
Private details and pay are refused (the person adds them in the app).
MCP tool
org_drafts_save 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

  • processstring (enum)required

    One of: hire, change_job, promote, move, leaving, probation, contract, rehire, proposal.

  • variant"promote" | "move" | "resign" | "probation"

    Proposals only: what is proposed.

  • person_idsstring[]

    Up to 50 items.

  • labelstringrequired

    1–120 characters.

  • dataobjectrequired
  • draft_idstring

Returns

8 fields
  • idstringrequired
  • processstring (enum)required

    One of: hire, change_job, promote, move, leaving, probation, contract, rehire, proposal.

  • variantstring | nullrequired

    Proposals: what is proposed (promote, move, resign or probation).

  • labelstringrequired
  • peopleobject[]required
    2 fields
    • idstringrequired
    • namestringrequired
  • saved_byobjectrequired
    2 fields
    • user_idstringrequired
    • namestring | nullrequired
  • saved_atstringrequired
  • created_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/drafts.save \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "process": "promote",
  "person_ids": [
    "p4"
  ],
  "label": "Promotion of Lukas",
  "data": {
    "input": {
      "person_id": "p4"
    }
  },
  "draft_id": "d2"
}'
Response
{
  "data": {
    "id": "d1",
    "process": "promote",
    "variant": null,
    "label": "Promotion of Lukas",
    "people": [],
    "saved_by": {
      "user_id": "usr6",
      "name": "Marta Rocha"
    },
    "saved_at": "2026-10-08T15:00:00.000Z",
    "created_at": "2026-10-07T10:00:00.000Z"
  }
}

List processes saved for later#

POST/v1/org/drafts.listRead

Lists the processes saved for later that you may carry on (newest first): what process, a short label, the people it is about, who saved it and when. Filter by process or person_id. Never the saved values (open one in the web app).

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

Input

  • processstring (enum)

    One of: hire, change_job, promote, move, leaving, probation, contract, rehire, proposal.

  • person_idstring
  • variant"promote" | "move" | "resign" | "probation"

Returns

An array of objects with 8 fields

An array of objects:

  • idstringrequired
  • processstring (enum)required

    One of: hire, change_job, promote, move, leaving, probation, contract, rehire, proposal.

  • variantstring | nullrequired

    Proposals: what is proposed (promote, move, resign or probation).

  • labelstringrequired
  • peopleobject[]required
    2 fields
    • idstringrequired
    • namestringrequired
  • saved_byobjectrequired
    2 fields
    • user_idstringrequired
    • namestring | nullrequired
  • saved_atstringrequired
  • created_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/drafts.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"process":"hire"}'
Response
{
  "data": [
    {
      "id": "d1",
      "process": "hire",
      "variant": null,
      "label": "Ana Lima · Engineer",
      "people": [],
      "saved_by": {
        "user_id": "usr6",
        "name": "Marta Rocha"
      },
      "saved_at": "2026-10-08T15:00:00.000Z",
      "created_at": "2026-10-07T10:00:00.000Z"
    },
    {
      "id": "d2",
      "process": "promote",
      "variant": null,
      "label": "Promotion of Lukas",
      "people": [
        {
          "id": "p4",
          "name": "Lukas Weber"
        }
      ],
      "saved_by": {
        "user_id": "usr6",
        "name": "Marta Rocha"
      },
      "saved_at": "2026-10-08T15:00:00.000Z",
      "created_at": "2026-10-07T10:00:00.000Z"
    }
  ]
}

Open a process saved for later#

POST/v1/org/drafts.getRead

One saved draft with the values as they were saved (data.input: the action input so far). Over an API key or MCP, private details and pay are left out. To finish it, run the process's action with data.input completed, then delete the draft with org_drafts_delete.

Who can call it
Manage key any Manage role
Me key anyone
Keys and apps
Private details and pay are left out.
MCP tool
org_drafts_get on HR Assistant, My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • draft_idstringrequired

Returns

9 fields
  • idstringrequired
  • processstring (enum)required

    One of: hire, change_job, promote, move, leaving, probation, contract, rehire, proposal.

  • variantstring | nullrequired

    Proposals: what is proposed (promote, move, resign or probation).

  • labelstringrequired
  • peopleobject[]required
    2 fields
    • idstringrequired
    • namestringrequired
  • saved_byobjectrequired
    2 fields
    • user_idstringrequired
    • namestring | nullrequired
  • saved_atstringrequired
  • created_atstringrequired
  • dataobjectrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/drafts.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"draft_id":"d1"}'
Response
{
  "data": {
    "id": "d1",
    "process": "hire",
    "variant": null,
    "label": "Ana Lima · Engineer",
    "people": [],
    "saved_by": {
      "user_id": "usr6",
      "name": "Marta Rocha"
    },
    "saved_at": "2026-10-08T15:00:00.000Z",
    "created_at": "2026-10-07T10:00:00.000Z",
    "data": {
      "input": {
        "given_name": "Ana",
        "family_name": "Lima",
        "title": "Engineer"
      },
      "form": {
        "step": 1
      }
    }
  }
}

Delete a process saved for later#

POST/v1/org/drafts.deleteDestructive

Deletes a saved draft (finished, or no longer needed). Anyone who may carry it on may delete it.

Who can call it
Manage key any Manage role
Me key anyone
MCP tool
org_drafts_delete on HR Assistant, My Workplace
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • draft_idstringrequired

Returns

  • idstringrequired
  • deletedtruerequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/drafts.delete \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"draft_id":"d1"}'
Response
{
  "data": {
    "id": "d1",
    "deleted": true
  }
}

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

Developer docs