API reference

People

The directory, one person's profile, profile changes and photos.

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

List people (directory)#

POST/v1/org/people.listRead

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

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

Input

as_ofstring
status"active" | "pre_hire" | "terminated" | "all"
qstring
Up to 100 characters.
unit_idstring
include_subunitsboolean
location_idstring
legal_entity_idstring
manager_idstring
joined_betweenobject
2 fields
- fromstringrequired
- tostringrequired
left_betweenobject
2 fields
- fromstringrequired
- tostringrequired

Returns

An array of objects with 15 fields

An array of objects:

idstringrequired
namestringrequired
given_namestringrequired
family_namestringrequired
preferred_namestring | nullrequired
work_emailstringrequired
titlestring | nullrequired
status"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

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl

curl https://api.bizisy.com/v1/org/people.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "joined_between": {
    "from": "2026-03-01",
    "to": "2026-03-31"
  },
  "left_between": {
    "from": "2026-01-01",
    "to": "2026-12-31"
  }
}'

Node

const res = await fetch('https://api.bizisy.com/v1/org/people.list', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "joined_between": {
      "from": "2026-03-01",
      "to": "2026-03-31"
    },
    "left_between": {
      "from": "2026-01-01",
      "to": "2026-12-31"
    }
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);

Python

import os
import requests

res = requests.post(
    "https://api.bizisy.com/v1/org/people.list",
    headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
    json={
        "joined_between": {
            "from": "2026-03-01",
            "to": "2026-03-31",
        },
        "left_between": {
            "from": "2026-01-01",
            "to": "2026-12-31",
        },
    },
)
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
    },
    {
      "id": "p3",
      "name": "Ana Ferreira",
      "given_name": "Ana",
      "family_name": "Ferreira",
      "preferred_name": null,
      "work_email": "ana@acme.test",
      "title": "Engineer",
      "status": "pre_hire",
      "start_date": "2024-01-15",
      "unit": null,
      "location": null,
      "manager": null,
      "invited": true,
      "has_login": true,
      "photo_url": null
    }
  ]
}

Get a person#

POST/v1/org/people.getRead

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

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

Input

person_idstringrequired
as_ofstring

Returns

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

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl

curl https://api.bizisy.com/v1/org/people.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"person_id":"p1","as_of":"2026-10-04"}'

Node

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

Python

import os
import requests

res = requests.post(
    "https://api.bizisy.com/v1/org/people.get",
    headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
    json={
        "person_id": "p1",
        "as_of": "2026-10-04",
    },
)
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"
    ]
  }
}

Update a person's profile#

POST/v1/org/people.update_profileWrite

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

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

Input

given_namestring
1–100 characters.
family_namestring
1–100 characters.
work_emailany
preferred_namestring | null
1–100 characters.
pronounsstring | null
Up to 40 characters.
work_phonestring | null
Pattern ^\+?[0-9 ().-]{3,40}$.
personal_emailany | null
personal_phonestring | null
Pattern ^\+?[0-9 ().-]{3,40}$.
addressobject | null
5 fields
- line1stringrequired
  1–200 characters.
- line2string
  Up to 200 characters.
- citystringrequired
  1–100 characters.
- postal_codestring
  Up to 20 characters.
- countryanyrequired
birthdaystring | null
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
person_idstringrequired

Returns

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

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl

curl https://api.bizisy.com/v1/org/people.update_profile \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "person_id": "p1",
  "given_name": "Ana Maria",
  "work_email": "ana.maria@acme.test",
  "address": null,
  "emergency_contacts": []
}'

Node

const res = await fetch('https://api.bizisy.com/v1/org/people.update_profile', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "person_id": "p1",
    "given_name": "Ana Maria",
    "work_email": "ana.maria@acme.test",
    "address": null,
    "emergency_contacts": []
  }),
});
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.update_profile",
    headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "person_id": "p1",
        "given_name": "Ana Maria",
        "work_email": "ana.maria@acme.test",
        "address": None,
        "emergency_contacts": [],
    },
)
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 Maria Ferreira",
    "given_name": "Ana Maria",
    "family_name": "Ferreira",
    "preferred_name": null,
    "work_email": "ana.maria@acme.test",
    "title": "Engineer",
    "status": "active",
    "start_date": "2024-01-15",
    "unit": {
      "id": "u2",
      "name": "Engineering"
    },
    "location": {
      "id": "l1",
      "name": "Head office"
    },
    "manager": {
      "id": "p2",
      "name": "Rui Costa",
      "title": "CTO",
      "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
    },
    "invited": true,
    "has_login": true,
    "photo_url": null,
    "pronouns": "she/her",
    "work_phone": "+351 210 000 000",
    "personal_email": null,
    "personal_phone": null,
    "address": null,
    "birthday": null,
    "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"
    ]
  }
}

Upload a person's photo#

POST/v1/org/people.photo.uploadWrite

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

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

Input

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

Returns

person_idstringrequired
photo_urlstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict payload_too_large rate_limited internal

curl

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

Node

const res = await fetch('https://api.bizisy.com/v1/org/people.photo.upload', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "person_id": "p1",
    "image_base64": "UklGRg=="
  }),
});
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.photo.upload",
    headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "person_id": "p1",
        "image_base64": "UklGRg==",
    },
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"])

Response

{
  "data": {
    "person_id": "p1",
    "photo_url": "https://acme.bizisy.com/api/photos/people/p1?v=01k0000000000000000000000d"
  }
}

Remove a person's photo#

POST/v1/org/people.photo.removeDestructive

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

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

Input

person_idstringrequired

Returns

person_idstringrequired
photo_urlstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl

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

Node

const res = await fetch('https://api.bizisy.com/v1/org/people.photo.remove', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "person_id": "p1"
  }),
});
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.photo.remove",
    headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "person_id": "p1",
    },
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"])

Response

{
  "data": {
    "person_id": "p1",
    "photo_url": null
  }
}

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