API reference

Jobs and employment

Hire, change jobs from a date, terminate, rehire and correct job history.

5 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, 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 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. Use dry_run first.

Who can call it: Manage key owner admin hr
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
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
titlestringrequired
1–120 characters.
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

Returns

31 fields

idstringrequired
namestringrequired
given_namestringrequired
family_namestringrequired
preferred_namestring | nullrequired
work_emailstringrequired
titlestring | nullrequired
status"pre_hire" | "active" | "terminated" | "none"required
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
emergency_contactsobject[] | nullrequired
3 fields
- namestringrequired
- relationshipstringrequired
- phonestringrequired
tax_idstring | nullrequired
social_security_numberstring | nullrequired
ibanstring | nullrequired
customobject[]required
6 fields
- keystringrequired
- labelstringrequired
- type"text" | "number" | "date" | "select" | "boolean" | "file"required
- tier"public" | "job" | "private"required
- valuestring | number | booleanrequired
  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.
- 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).
jobobject | nullrequired
17 fields
- idstringrequired
- valid_fromstringrequired
- valid_tostring | nullrequired
- titlestringrequired
- 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
- contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
- contract_end_datestring | nullrequired
- probation_end_datestring | nullrequired
- weekly_hoursnumber | nullrequired
- notice_period_daysinteger | nullrequired
historyobject[] | nullrequired
17 fields
- idstringrequired
- valid_fromstringrequired
- valid_tostring | nullrequired
- titlestringrequired
- 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
- contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
- contract_end_datestring | nullrequired
- probation_end_datestring | nullrequired
- weekly_hoursnumber | nullrequired
- notice_period_daysinteger | nullrequired
reportsobject[]required
4 fields
- idstringrequired
- namestringrequired
- titlestring | nullrequired
- photo_urlstring | nullrequired
visible_tiers"public" | "private" | "job" | "pay"[]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

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"
}'

Node

const res = await fetch('https://api.bizisy.com/v1/org/people.hire', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "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"
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);

Python

import os, uuid
import requests

res = requests.post(
    "https://api.bizisy.com/v1/org/people.hire",
    headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "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": None,
        "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": None,
        "legal_entity_id": None,
        "employment_type": "contractor",
        "fte": 0.5,
        "start_date": "2026-11-02",
    },
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"])

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,
    "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",
      "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,
      "contract_type": "fixed_term",
      "contract_end_date": "2026-01-14",
      "probation_end_date": "2024-07-14",
      "weekly_hours": 40,
      "notice_period_days": 30
    },
    "history": [
      {
        "id": "j1",
        "valid_from": "2024-01-15",
        "valid_to": null,
        "title": "Engineer",
        "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,
        "contract_type": "fixed_term",
        "contract_end_date": "2026-01-14",
        "probation_end_date": "2024-07-14",
        "weekly_hours": 40,
        "notice_period_days": 30
      }
    ],
    "reports": [],
    "visible_tiers": [
      "public",
      "job"
    ],
    "manager_default": {
      "unit_id": "u2",
      "unit_name": "Engineering"
    }
  }
}

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). 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
1–120 characters.
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.
person_idstringrequired
effective_datestringrequired
reason"change" | "promotion" | "transfer"required

Returns

33 fields

idstringrequired
namestringrequired
given_namestringrequired
family_namestringrequired
preferred_namestring | nullrequired
work_emailstringrequired
titlestring | nullrequired
status"pre_hire" | "active" | "terminated" | "none"required
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
emergency_contactsobject[] | nullrequired
3 fields
- namestringrequired
- relationshipstringrequired
- phonestringrequired
tax_idstring | nullrequired
social_security_numberstring | nullrequired
ibanstring | nullrequired
customobject[]required
6 fields
- keystringrequired
- labelstringrequired
- type"text" | "number" | "date" | "select" | "boolean" | "file"required
- tier"public" | "job" | "private"required
- valuestring | number | booleanrequired
  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.
- 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).
jobobject | nullrequired
17 fields
- idstringrequired
- valid_fromstringrequired
- valid_tostring | nullrequired
- titlestringrequired
- 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
- contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
- contract_end_datestring | nullrequired
- probation_end_datestring | nullrequired
- weekly_hoursnumber | nullrequired
- notice_period_daysinteger | nullrequired
historyobject[] | nullrequired
17 fields
- idstringrequired
- valid_fromstringrequired
- valid_tostring | nullrequired
- titlestringrequired
- 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
- contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
- contract_end_datestring | nullrequired
- probation_end_datestring | nullrequired
- weekly_hoursnumber | nullrequired
- notice_period_daysinteger | nullrequired
reportsobject[]required
4 fields
- idstringrequired
- namestringrequired
- titlestring | nullrequired
- photo_urlstring | nullrequired
visible_tiers"public" | "private" | "job" | "pay"[]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
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

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
}'

Node

const res = await fetch('https://api.bizisy.com/v1/org/people.change_job', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "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
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);

Python

import os, uuid
import requests

res = requests.post(
    "https://api.bizisy.com/v1/org/people.change_job",
    headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "person_id": "p1",
        "effective_date": "2026-10-05",
        "reason": "transfer",
        "unit_id": "u3",
        "manager_id": None,
        "location_id": "l2",
        "legal_entity_id": "e1",
        "employment_type": "part_time",
        "fte": 0.8,
    },
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"])

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,
    "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",
      "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,
      "contract_type": "fixed_term",
      "contract_end_date": "2026-01-14",
      "probation_end_date": "2024-07-14",
      "weekly_hours": 40,
      "notice_period_days": 30
    },
    "history": [
      {
        "id": "j1",
        "valid_from": "2024-01-15",
        "valid_to": null,
        "title": "Engineer",
        "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,
        "contract_type": "fixed_term",
        "contract_end_date": "2026-01-14",
        "probation_end_date": "2024-07-14",
        "weekly_hours": 40,
        "notice_period_days": 30
      }
    ],
    "reports": [],
    "visible_tiers": [
      "public",
      "job"
    ],
    "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
  }
}

Terminate employment#

POST/v1/org/people.terminateDestructive

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"). 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.

Returns

personobjectrequired
30 fields
- idstringrequired
- namestringrequired
- given_namestringrequired
- family_namestringrequired
- preferred_namestring | nullrequired
- work_emailstringrequired
- titlestring | nullrequired
- status"pre_hire" | "active" | "terminated" | "none"required
- 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
- emergency_contactsobject[] | nullrequired
  3 fields
  - namestringrequired
  - relationshipstringrequired
  - phonestringrequired
- tax_idstring | nullrequired
- social_security_numberstring | nullrequired
- ibanstring | nullrequired
- customobject[]required
  6 fields
  - keystringrequired
  - labelstringrequired
  - type"text" | "number" | "date" | "select" | "boolean" | "file"required
  - tier"public" | "job" | "private"required
  - valuestring | number | booleanrequired
    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.
  - 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).
- jobobject | nullrequired
  17 fields
  - idstringrequired
  - valid_fromstringrequired
  - valid_tostring | nullrequired
  - titlestringrequired
  - 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
  - contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
  - contract_end_datestring | nullrequired
  - probation_end_datestring | nullrequired
  - weekly_hoursnumber | nullrequired
  - notice_period_daysinteger | nullrequired
- historyobject[] | nullrequired
  17 fields
  - idstringrequired
  - valid_fromstringrequired
  - valid_tostring | nullrequired
  - titlestringrequired
  - 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
  - contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
  - contract_end_datestring | nullrequired
  - probation_end_datestring | nullrequired
  - weekly_hoursnumber | nullrequired
  - notice_period_daysinteger | nullrequired
- reportsobject[]required
  4 fields
  - idstringrequired
  - namestringrequired
  - titlestring | nullrequired
  - photo_urlstring | nullrequired
- visible_tiers"public" | "private" | "job" | "pay"[]required
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"}'

Node

const res = await fetch('https://api.bizisy.com/v1/org/people.terminate', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "person_id": "p1",
    "last_day": "2026-10-31",
    "reason": "resigned"
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);

Python

import os, uuid
import requests

res = requests.post(
    "https://api.bizisy.com/v1/org/people.terminate",
    headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "person_id": "p1",
        "last_day": "2026-10-31",
        "reason": "resigned",
    },
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"])

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,
      "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",
        "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,
        "contract_type": "fixed_term",
        "contract_end_date": "2026-01-14",
        "probation_end_date": "2024-07-14",
        "weekly_hours": 40,
        "notice_period_days": 30
      },
      "history": [
        {
          "id": "j1",
          "valid_from": "2024-01-15",
          "valid_to": null,
          "title": "Engineer",
          "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,
          "contract_type": "fixed_term",
          "contract_end_date": "2026-01-14",
          "probation_end_date": "2024-07-14",
          "weekly_hours": 40,
          "notice_period_days": 30
        }
      ],
      "reports": [],
      "visible_tiers": [
        "public",
        "job"
      ]
    },
    "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

titlestringrequired
1–120 characters.
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.
person_idstringrequired
start_datestringrequired

Returns

32 fields

idstringrequired
namestringrequired
given_namestringrequired
family_namestringrequired
preferred_namestring | nullrequired
work_emailstringrequired
titlestring | nullrequired
status"pre_hire" | "active" | "terminated" | "none"required
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
emergency_contactsobject[] | nullrequired
3 fields
- namestringrequired
- relationshipstringrequired
- phonestringrequired
tax_idstring | nullrequired
social_security_numberstring | nullrequired
ibanstring | nullrequired
customobject[]required
6 fields
- keystringrequired
- labelstringrequired
- type"text" | "number" | "date" | "select" | "boolean" | "file"required
- tier"public" | "job" | "private"required
- valuestring | number | booleanrequired
  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.
- 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).
jobobject | nullrequired
17 fields
- idstringrequired
- valid_fromstringrequired
- valid_tostring | nullrequired
- titlestringrequired
- 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
- contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
- contract_end_datestring | nullrequired
- probation_end_datestring | nullrequired
- weekly_hoursnumber | nullrequired
- notice_period_daysinteger | nullrequired
historyobject[] | nullrequired
17 fields
- idstringrequired
- valid_fromstringrequired
- valid_tostring | nullrequired
- titlestringrequired
- 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
- contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
- contract_end_datestring | nullrequired
- probation_end_datestring | nullrequired
- weekly_hoursnumber | nullrequired
- notice_period_daysinteger | nullrequired
reportsobject[]required
4 fields
- idstringrequired
- namestringrequired
- titlestring | nullrequired
- photo_urlstring | nullrequired
visible_tiers"public" | "private" | "job" | "pay"[]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
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

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
}'

Node

const res = await fetch('https://api.bizisy.com/v1/org/people.rehire', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "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
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);

Python

import os, uuid
import requests

res = requests.post(
    "https://api.bizisy.com/v1/org/people.rehire",
    headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "person_id": "p1",
        "start_date": "2026-11-02",
        "title": "Engineer",
        "unit_id": "u2",
        "manager_id": "p2",
        "location_id": None,
        "legal_entity_id": "e1",
        "employment_type": "intern",
        "fte": 1,
    },
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"])

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,
    "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",
      "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,
      "contract_type": "fixed_term",
      "contract_end_date": "2026-01-14",
      "probation_end_date": "2024-07-14",
      "weekly_hours": 40,
      "notice_period_days": 30
    },
    "history": [
      {
        "id": "j1",
        "valid_from": "2024-01-15",
        "valid_to": null,
        "title": "Engineer",
        "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,
        "contract_type": "fixed_term",
        "contract_end_date": "2026-01-14",
        "probation_end_date": "2024-07-14",
        "weekly_hours": 40,
        "notice_period_days": 30
      }
    ],
    "reports": [],
    "visible_tiers": [
      "public",
      "job"
    ],
    "approval": null,
    "manager_default": 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, valid_to (the day after the last day) and end_reason 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
1–120 characters.
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.
job_idstringrequired
valid_fromstring
valid_tostring | null
end_reasonstring | null
Up to 200 characters.

Returns

31 fields

idstringrequired
namestringrequired
given_namestringrequired
family_namestringrequired
preferred_namestring | nullrequired
work_emailstringrequired
titlestring | nullrequired
status"pre_hire" | "active" | "terminated" | "none"required
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
emergency_contactsobject[] | nullrequired
3 fields
- namestringrequired
- relationshipstringrequired
- phonestringrequired
tax_idstring | nullrequired
social_security_numberstring | nullrequired
ibanstring | nullrequired
customobject[]required
6 fields
- keystringrequired
- labelstringrequired
- type"text" | "number" | "date" | "select" | "boolean" | "file"required
- tier"public" | "job" | "private"required
- valuestring | number | booleanrequired
  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.
- 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).
jobobject | nullrequired
17 fields
- idstringrequired
- valid_fromstringrequired
- valid_tostring | nullrequired
- titlestringrequired
- 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
- contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
- contract_end_datestring | nullrequired
- probation_end_datestring | nullrequired
- weekly_hoursnumber | nullrequired
- notice_period_daysinteger | nullrequired
historyobject[] | nullrequired
17 fields
- idstringrequired
- valid_fromstringrequired
- valid_tostring | nullrequired
- titlestringrequired
- 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
- contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"required
- contract_end_datestring | nullrequired
- probation_end_datestring | nullrequired
- weekly_hoursnumber | nullrequired
- notice_period_daysinteger | nullrequired
reportsobject[]required
4 fields
- idstringrequired
- namestringrequired
- titlestring | nullrequired
- photo_urlstring | nullrequired
visible_tiers"public" | "private" | "job" | "pay"[]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.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
}'

Node

const res = await fetch('https://api.bizisy.com/v1/org/people.correct_job', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "job_id": "j1",
    "valid_from": "2024-01-16",
    "valid_to": null,
    "end_reason": null,
    "unit_id": null,
    "fte": 0.9
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);

Python

import os, uuid
import requests

res = requests.post(
    "https://api.bizisy.com/v1/org/people.correct_job",
    headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "job_id": "j1",
        "valid_from": "2024-01-16",
        "valid_to": None,
        "end_reason": None,
        "unit_id": None,
        "fte": 0.9,
    },
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"])

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,
    "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",
      "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,
      "contract_type": "fixed_term",
      "contract_end_date": "2026-01-14",
      "probation_end_date": "2024-07-14",
      "weekly_hours": 40,
      "notice_period_days": 30
    },
    "history": [
      {
        "id": "j1",
        "valid_from": "2024-01-15",
        "valid_to": null,
        "title": "Engineer",
        "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,
        "contract_type": "fixed_term",
        "contract_end_date": "2026-01-14",
        "probation_end_date": "2024-07-14",
        "weekly_hours": 40,
        "notice_period_days": 30
      }
    ],
    "reports": [],
    "visible_tiers": [
      "public",
      "job"
    ],
    "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
    }
  }
}

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