API reference
Invites and outside access
Invite people by email alone (they add their own details), invite people to sign in, give outsiders access with a custom role and an end date, list and revoke invites, and preview whom a role covers.
12 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.
Withdraw an invitation#
POST/v1/org/people.withdrawDestructive
Withdraws the invitation of a person invited by email who is still waiting for their details (status invited): their record, any login, open invite and everything they or HR entered are erased, as when it is clear they won't join (spec invite-by-email D9). Irreversible; the work email can be invited again. Only invited people (others: org_people_terminate, then org_people_erase). Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_people_withdrawon HR Assistant- Preview
?dry_run=trueruns 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_idstringrequiredwithdrawntruerequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/people.withdraw \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"person_id":"p9"}'const res = await fetch('https://api.bizisy.com/v1/org/people.withdraw', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_id": "p9"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/people.withdraw",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p9",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"person_id": "p9",
"withdrawn": true
}
}Invite a person to sign in#
POST/v1/org/invites.createWrite
Creates a sign-in invite link for a person. role is member, viewer, hr or admin (hr and admin only for owners/admins); if the person already has a membership, omit role to keep theirs (a different role is a conflict: change it with platform_members_set_role). Bizisy emails the link to the person's work email (reply-to you); email.status says whether it was sent (email.reason rate_limited: the organization reached its daily email limit), and email.message says what to tell the user. Returns the link once as well, in the web app only: API keys and connected AI apps get url null (the link is a sign-in credential), so if email.status is not sent, tell the user to invite the person again from Bizisy and share the link privately. It expires in 14 days. Inviting again revokes their earlier open link. People who have left, or already have a login, cannot be invited.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- url is null: the sign-in link is only emailed to the person.
- MCP tool
org_invites_createon HR Assistant- Preview
?dry_run=trueruns 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_idstringrequiredrole"member" | "hr" | "admin" | "viewer"role_idstringA custom role (
platform_roles_list) instead of role: owners and admins, in the app only.
Returns
invite_idstringrequiredurlstring | nullrequiredThe sign-in link, only for a person signed in to Bizisy; null for API keys and connected apps.
expires_atstringrequiredemailobjectrequired3 fields
status"sent" | "failed" | "skipped"requiredmessagestringrequiredreason"rate_limited"
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/invites.create \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"person_id":"p1","role":"viewer"}'const res = await fetch('https://api.bizisy.com/v1/org/invites.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_id": "p1",
"role": "viewer"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/invites.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p1",
"role": "viewer",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"invite_id": "i1",
"url": "https://acme.bizisy.com/invite#token=tok",
"expires_at": "2026-10-18T10:00:00.000Z",
"email": {
"status": "sent",
"message": "We emailed the link to bea@acme.pt."
}
}
}Invite several people to sign in#
POST/v1/org/invites.create_manyWrite
Sends sign-in invites to several current people (employed or starting) who have no login, no open invite and no scheduled one (HR-8): person_ids (1–200), or all_without_login true for everyone like that. role: member (default), viewer, hr or admin (hr and admin only for owners and admins). when: now (default) or start (each at 08:00 company time on their first day; people already started get it now). All or nothing: when a named person can't be invited (left, has a login, already invited, an outsider, tied to an owner's or admin's login), nothing is sent and details.problems lists each {person_id, problem}. With all_without_login, people tied to an owner's or admin's login are left out for HR and listed in skipped. An open invite whose email was not sent (the daily email limit) is sent again. The links are emailed only, never returned, also over an API key or MCP (copy one from the person's profile in the app if an email fails). Owners, admins and HR. Use dry_run first.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- The sign-in links are only emailed to the people, never returned.
- MCP tool
org_invites_create_manyon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
person_idsstring[]1–200 items.
all_without_loginbooleanrole"member" | "viewer" | "hr" | "admin"when"now" | "start"Default
"now".
Returns
invitedobject[]required5 fields
person_idstringrequirednamestringrequiredstatus"sent" | "scheduled"requiredonstringrequiredThe company-local day it was or will be sent.
emailobject | nullrequiredFor invites sent now: whether the email went out (null when scheduled).
3 fields
status"sent" | "failed" | "skipped"requiredmessagestringrequiredreason"rate_limited"
skippedobject[]requiredall_without_login only: people left out (tied to an owner's or admin's login, which only owners and admins invite).
3 fields
person_idstringrequirednamestringrequiredreasonstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/invites.create_many \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"all_without_login":true,"when":"start","role":"member"}'const res = await fetch('https://api.bizisy.com/v1/org/invites.create_many', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"all_without_login": true,
"when": "start",
"role": "member"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/invites.create_many",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"all_without_login": True,
"when": "start",
"role": "member",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"invited": [
{
"person_id": "p7",
"name": "João Pereira",
"status": "sent",
"on": "2026-10-09",
"email": {
"status": "sent",
"message": "We emailed the link to joao@acme.test."
}
},
{
"person_id": "p5",
"name": "Inês Martins",
"status": "scheduled",
"on": "2026-11-02",
"email": null
}
],
"skipped": [
{
"person_id": "p8",
"name": "Maria Vasconcelos",
"reason": "Tied to an owner's or admin's login: only owners and admins can invite them."
}
]
}
}List invites#
POST/v1/org/invites.listRead
Lists invites, newest first. By default only open ones (not accepted, revoked or expired); include_closed returns all. Filter by person_id. Links are never shown again: to resend, create a new invite.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_invites_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
person_idstringinclude_closedbooleanDefault
false.
Returns
An array of objects with 8 fields
An array of objects:
idstringrequiredperson_idstringrequiredemailstringrequiredrolestringrequiredcreated_atstringrequiredexpires_atstringrequiredaccepted_atstring | nullrequiredrevoked_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/invites.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"person_id":"p1","include_closed":true}'const res = await fetch('https://api.bizisy.com/v1/org/invites.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"person_id": "p1",
"include_closed": true
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/invites.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"person_id": "p1",
"include_closed": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": [
{
"id": "i1",
"person_id": "p1",
"email": "ana@acme.test",
"role": "member",
"created_at": "2026-10-04T10:00:00.000Z",
"expires_at": "2026-10-18T10:00:00.000Z",
"accepted_at": null,
"revoked_at": "2026-10-05T10:00:00.000Z"
}
]
}Revoke an invite#
POST/v1/org/invites.revokeDestructive
Revokes an open invite so its link stops working; the login it would have created is removed. Accepted invites cannot be revoked (disable the member instead). Revoking an already revoked invite is a no-op.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_invites_revokeon HR Assistant- Preview
?dry_run=trueruns 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
invite_idstringrequired
Returns
8 fields
idstringrequiredperson_idstringrequiredemailstringrequiredrolestringrequiredcreated_atstringrequiredexpires_atstringrequiredaccepted_atstring | nullrequiredrevoked_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/invites.revoke \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"invite_id":"i1"}'const res = await fetch('https://api.bizisy.com/v1/org/invites.revoke', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"invite_id": "i1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/invites.revoke",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"invite_id": "i1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "i1",
"person_id": "p1",
"email": "ana@acme.test",
"role": "member",
"created_at": "2026-10-04T10:00:00.000Z",
"expires_at": "2026-10-18T10:00:00.000Z",
"accepted_at": null,
"revoked_at": "2026-10-05T10:00:00.000Z"
}
}Schedule or cancel a sign-in invite#
POST/v1/org/invites.scheduleWrite
Sends a person's sign-in invite on a later day (on: YYYY-MM-DD, after today, at 08:00 company time; for example their first day), or cancels the scheduled one (on: null). role: member (default), viewer, hr or admin (hr and admin only for owners and admins). It is sent as you, if you may still invite then; otherwise it is not sent and org_invites_scheduled says why. To send it now, use org_invites_create. People who have left, or already have a login, cannot be scheduled. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_invites_scheduleon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
person_idstringrequiredonstring | nullrequiredrole"member" | "hr" | "admin" | "viewer"
Returns
person_idstringrequiredonstring | nullrequiredThe company-local day it goes out (08:00); null once cancelled or when it could not be sent.
rolestring | nullrequiredscheduled_bystring | nullrequiredWho scheduled it (their name).
problemstring | nullrequiredWhy the last scheduled invite was not sent.
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/invites.schedule \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"person_id":"p7","on":"2026-11-02","role":"viewer"}'const res = await fetch('https://api.bizisy.com/v1/org/invites.schedule', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_id": "p7",
"on": "2026-11-02",
"role": "viewer"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/invites.schedule",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p7",
"on": "2026-11-02",
"role": "viewer",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"person_id": "p7",
"on": "2026-11-02",
"role": "viewer",
"scheduled_by": "Marta Rocha",
"problem": null
}
}List scheduled sign-in invites#
POST/v1/org/invites.scheduledRead
Invites scheduled for a later day (with a hire, or org_invites_schedule): who, which day, the role, who scheduled it, and problem when one could not be sent (the scheduler may no longer invite, the person left or already has a login). Filter by person_id. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_invites_scheduledon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
person_idstring
Returns
An array of objects:
person_idstringrequiredonstring | nullrequiredThe company-local day it goes out (08:00); null once cancelled or when it could not be sent.
rolestring | nullrequiredscheduled_bystring | nullrequiredWho scheduled it (their name).
problemstring | nullrequiredWhy the last scheduled invite was not sent.
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/invites.scheduled \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"person_id":"p7"}'const res = await fetch('https://api.bizisy.com/v1/org/invites.scheduled', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"person_id": "p7"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/invites.scheduled",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"person_id": "p7",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": [
{
"person_id": "p7",
"on": "2026-11-02",
"role": "member",
"scheduled_by": "Marta Rocha",
"problem": null
},
{
"person_id": "p8",
"on": null,
"role": "member",
"scheduled_by": "Marta Rocha",
"problem": "The person who scheduled it no longer has access to Bizisy."
}
]
}Invite people by email#
POST/v1/org/people.inviteWrite
Invites people from their work emails alone (spec invite-by-email): each becomes an invited person (status invited) who signs in and adds their own details; HR or their planned manager can fill in the rest. Optional per line: given_name, family_name, title (as typed) or title_id, start_date, unit_id, manager_id, location_id, legal_entity_id. A line with names, title and start_date is registered at once (as a hire, onboarding checklists included). They are registered automatically once names, title and start date are known (org_people_set_details; job details they suggest themselves wait for HR). Invited people are not headcount and are never billed until their job starts. send: now (default: the sign-in invite is emailed to each; the links themselves are returned only in the web app, never to an API key or MCP: invite.url is null there) or none. role: member (default), viewer, hr or admin (hr and admin only for owners and admins). All or nothing: when any line has a problem (an email already used or listed twice), nothing is created and details.problems lists each {index, work_email, problem}. At most 200 lines per call and 500 people waiting for their details at a time. Owners, admins and HR. Use dry_run first.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Each invite.url is null: the sign-in links are only emailed to the people.
- MCP tool
org_people_inviteon HR Assistant- Preview
?dry_run=trueruns 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
peopleobject[]required1–200 items.
10 fields
work_emailanyrequiredgiven_namestring1–100 characters.
family_namestring1–100 characters.
titlestringThe 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_idstringA job title from
org_titles_list, instead of title.start_datestringTheir first day (YYYY-MM-DD); a future date makes them pre_hire once registered.
unit_idstring | nullmanager_idstring | nulllocation_idstring | nulllegal_entity_idstring | null
send"now" | "none"Default
"now".role"member" | "hr" | "admin" | "viewer"
Returns
peopleobject[]required6 fields
idstringrequiredwork_emailstringrequirednamestringrequiredTheir name, or the work email until they have one.
status"invited" | "pre_hire" | "active"requiredmissing"given_name" | "family_name" | "title" | "start_date"[]requiredinviteobject | nullrequiredThe sign-in invite (null with send none).
3 fields
urlstring | nullrequiredThe sign-in link, only in the web app; null for API keys and connected apps.
expires_atstringrequiredemailobjectrequired3 fields
status"sent" | "failed" | "skipped"requiredmessagestringrequiredreason"rate_limited"
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/people.invite \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"people": [
{
"work_email": "rita.lima@acme.test"
},
{
"work_email": "joao.matos@acme.test",
"given_name": "João",
"title": "Designer",
"start_date": "2026-11-02",
"manager_id": "p2"
}
],
"send": "now",
"role": "member"
}'const res = await fetch('https://api.bizisy.com/v1/org/people.invite', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"people": [
{
"work_email": "rita.lima@acme.test"
},
{
"work_email": "joao.matos@acme.test",
"given_name": "João",
"title": "Designer",
"start_date": "2026-11-02",
"manager_id": "p2"
}
],
"send": "now",
"role": "member"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/people.invite",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"people": [
{
"work_email": "rita.lima@acme.test",
},
{
"work_email": "joao.matos@acme.test",
"given_name": "João",
"title": "Designer",
"start_date": "2026-11-02",
"manager_id": "p2",
},
],
"send": "now",
"role": "member",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"people": [
{
"id": "p9",
"work_email": "rita@acme.test",
"name": "rita@acme.test",
"status": "invited",
"missing": [
"given_name",
"family_name",
"title",
"start_date"
],
"invite": {
"url": "https://acme.bizisy.com/invite#token=x",
"expires_at": "2026-10-18T10:00:00.000Z",
"email": {
"status": "sent",
"message": "We emailed the link to rita@acme.test."
}
}
}
]
}
}Fill in an invited person's details#
POST/v1/org/people.set_detailsWrite
Sets the details of a person invited by email (status invited): given_name, family_name and their job as on hire (title as typed or title_id, start_date, unit_id, manager_id, location_id, legal_entity_id, employment_type, fte, contract terms; null clears one). They are registered (first job row, onboarding checklists) as soon as names, title and start_date are known; missing lists what is still needed. Refused while job details they or their manager suggested wait for approval (decide that request first). Registered people: org_people_update_profile and org_people_change_job instead. Owners, admins and HR, and roles that edit the people they cover.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_people_set_detailson HR Assistant- Preview
?dry_run=trueruns 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_idstringrequiredgiven_namestring1–100 characters.
family_namestring1–100 characters.
titlestringThe 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_idstringA job title from
org_titles_list, instead of title.start_datestringTheir first day (YYYY-MM-DD); a future date makes them pre_hire once registered.
unit_idstring | nullmanager_idstring | nulllocation_idstring | nulllegal_entity_idstring | nullemployment_type"full_time" | "part_time" | "contractor" | "intern"ftenumberFrom 0 to 1.
contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"contract_end_datestring | nullprobation_end_datestring | nullweekly_hoursnumber | nullFrom 0 to 80.
notice_period_daysinteger | nullFrom 0 to 365.
Returns
personobjectrequired35 fields
idstringrequirednamestringrequiredgiven_namestringrequiredfamily_namestringrequiredpreferred_namestring | nullrequiredwork_emailstringrequiredtitlestring | nullrequiredstatus"invited" | "pre_hire" | "active" | "terminated" | "none"requiredinvited: waiting for their details (names, title, start date), not employed yet; pre_hire: starts later; active; terminated: has left; none: no job.
start_datestring | nullrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
invitedbooleanrequiredhas_loginbooleanrequiredphoto_urlstring | nullrequiredpronounsstring | nullrequiredwork_phonestring | nullrequiredpersonal_emailstring | nullrequiredpersonal_phonestring | nullrequiredaddressobject | nullrequired5 fields
line1stringrequiredline2stringcitystringrequiredpostal_codestringcountrystringrequired
birthdaystring | nullrequiredsex"female" | "male" | "another" | "undisclosed"requiredFor 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[] | nullrequired3 fields
namestringrequiredrelationshipstringrequiredphonestringrequired
tax_idstring | nullrequiredsocial_security_numberstring | nullrequiredibanstring | nullrequiredcustomobject[]required7 fields
keystringrequiredlabelstringrequiredtypestring (enum)requiredOne of:
text,number,date,select,boolean,file,person,table.tier"public" | "job" | "private"requiredvaluestring | number | boolean | object[]requiredFor type file: the document id (download it with
documents_downloadordocuments_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 inorg_fields_list).fileobject | nullType file only: the file, or null when none is attached.
4 fields
namestring | nullrequiredThe file name; null over an API key or MCP for someone else's file.
sizeintegerrequiredcontent_typestringrequiredpreviewablebooleanrequiredThe web app can show it (PDF, PNG, JPEG, WebP).
personobject | nullType person only: who it names (null when not set, or not someone you may see).
4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
jobobject | nullrequired23 fields
idstringrequiredvalid_fromstringrequiredvalid_tostring | nullrequiredtitlestringrequiredThe job title as the catalog names it now (reports and grouping use this).
title_idstring | nullrequiredThe catalog title (
org_titles_list); null while not in the catalog yet.display_titlestring | nullrequiredA different title shown on the profile, chart and directory; null: the catalog title.
unitobject | nullrequired2 fields
idstringrequirednamestringrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
legal_entityobject | nullrequired2 fields
idstringrequirednamestringrequired
employment_type"full_time" | "part_time" | "contractor" | "intern"requiredftenumberrequiredreasonstringrequiredend_reasonstring | nullrequiredleaving_typestring (enum)requiredWhy the employment ended (structured); null: not recorded or still employed.
One of:
resignation,retirement,dismissal,redundancy,end_of_contract,mutual_agreement,death,other.toldboolean | nullrequiredWith 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_toldor the day passes. null on other rows.contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredcontract_end_datestring | nullrequiredprobation_end_datestring | nullrequiredweekly_hoursnumber | nullrequirednotice_period_daysinteger | nullrequiredcustomobject[]requiredJob 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
keystringrequiredlabelstringrequiredtypestring (enum)requiredOne of:
text,number,date,select,boolean,file,person,table.tier"public" | "job" | "private"requiredvaluestring | number | boolean | object[]requiredFor type file: the document id (download it with
documents_downloadordocuments_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 inorg_fields_list).fileobject | nullType file only: the file, or null when none is attached.
4 fields
namestring | nullrequiredThe file name; null over an API key or MCP for someone else's file.
sizeintegerrequiredcontent_typestringrequiredpreviewablebooleanrequiredThe web app can show it (PDF, PNG, JPEG, WebP).
personobject | nullType person only: who it names (null when not set, or not someone you may see).
4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
regrettedboolean | nullPrivate (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[] | nullrequired23 fields
idstringrequiredvalid_fromstringrequiredvalid_tostring | nullrequiredtitlestringrequiredThe job title as the catalog names it now (reports and grouping use this).
title_idstring | nullrequiredThe catalog title (
org_titles_list); null while not in the catalog yet.display_titlestring | nullrequiredA different title shown on the profile, chart and directory; null: the catalog title.
unitobject | nullrequired2 fields
idstringrequirednamestringrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
legal_entityobject | nullrequired2 fields
idstringrequirednamestringrequired
employment_type"full_time" | "part_time" | "contractor" | "intern"requiredftenumberrequiredreasonstringrequiredend_reasonstring | nullrequiredleaving_typestring (enum)requiredWhy the employment ended (structured); null: not recorded or still employed.
One of:
resignation,retirement,dismissal,redundancy,end_of_contract,mutual_agreement,death,other.toldboolean | nullrequiredWith 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_toldor the day passes. null on other rows.contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredcontract_end_datestring | nullrequiredprobation_end_datestring | nullrequiredweekly_hoursnumber | nullrequirednotice_period_daysinteger | nullrequiredcustomobject[]requiredJob 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
keystringrequiredlabelstringrequiredtypestring (enum)requiredOne of:
text,number,date,select,boolean,file,person,table.tier"public" | "job" | "private"requiredvaluestring | number | boolean | object[]requiredFor type file: the document id (download it with
documents_downloadordocuments_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 inorg_fields_list).fileobject | nullType file only: the file, or null when none is attached.
4 fields
namestring | nullrequiredThe file name; null over an API key or MCP for someone else's file.
sizeintegerrequiredcontent_typestringrequiredpreviewablebooleanrequiredThe web app can show it (PDF, PNG, JPEG, WebP).
personobject | nullType person only: who it names (null when not set, or not someone you may see).
4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
regrettedboolean | nullPrivate (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[]required4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
visible_tiers"public" | "private" | "job" | "pay"[]requiredplannedobject | nullrequiredWhile invited (status invited): the job details known so far (job tier; null otherwise or when not visible).
14 fields
titlestring | nullrequiredtitle_idstring | nullrequiredstart_datestring | nullrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
legal_entityobject | nullrequired2 fields
idstringrequirednamestringrequired
employment_type"full_time" | "part_time" | "contractor" | "intern"requiredftenumber | nullrequiredcontract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredcontract_end_datestring | nullrequiredprobation_end_datestring | nullrequiredweekly_hoursnumber | nullrequirednotice_period_daysinteger | nullrequired
missing"given_name" | "family_name" | "title" | "start_date"[]requiredWhile invited: what is still needed to register them (given_name, family_name, title, start_date); [] otherwise.
dotted_managersobject[]requiredDotted-line managers today (spec structure-over-time D10): they see job details, never approve.
4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
dotted_reportsobject[]requiredPeople this person has a dotted line to today.
4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
registeredbooleanrequiredTrue when this call registered them (their first job row was written).
missing"given_name" | "family_name" | "title" | "start_date"[]requiredWhat is still needed to register them; [] once registered.
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/people.set_details \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"person_id": "p9",
"given_name": "Rita",
"family_name": "Sousa",
"title": "Designer",
"start_date": "2026-11-02",
"manager_id": "p2",
"unit_id": null
}'const res = await fetch('https://api.bizisy.com/v1/org/people.set_details', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_id": "p9",
"given_name": "Rita",
"family_name": "Sousa",
"title": "Designer",
"start_date": "2026-11-02",
"manager_id": "p2",
"unit_id": null
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/people.set_details",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p9",
"given_name": "Rita",
"family_name": "Sousa",
"title": "Designer",
"start_date": "2026-11-02",
"manager_id": "p2",
"unit_id": None,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"person": {
"id": "p9",
"name": "Rita Sousa",
"given_name": "Rita",
"family_name": "Sousa",
"preferred_name": null,
"work_email": "rita@acme.test",
"title": null,
"status": "invited",
"start_date": null,
"unit": null,
"location": null,
"manager": null,
"invited": true,
"has_login": false,
"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": null,
"history": [],
"reports": [],
"visible_tiers": [
"public",
"job"
],
"planned": {
"title": "Designer",
"title_id": null,
"start_date": null,
"unit": null,
"manager": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"location": null,
"legal_entity": null,
"employment_type": null,
"fte": null,
"contract_type": null,
"contract_end_date": null,
"probation_end_date": null,
"weekly_hours": null,
"notice_period_days": null
},
"missing": [
"start_date"
],
"dotted_managers": [
{
"id": "p7",
"name": "João Pereira",
"title": "Sales Lead",
"photo_url": null
}
],
"dotted_reports": []
},
"registered": false,
"missing": [
"start_date"
]
}
}Preview who a role covers#
POST/v1/org/access.previewRead
For the role editor (owners and admins): how many people a scope covers today and the first 50 of them (names only). An empty scope covers everyone. Unknown ids simply match nobody. Groups are evaluated through what the role's areas see (send areas; without them job conditions are not met), and warnings says when a group can't scope a role with those areas.
- Who can call it
- Manage key owner admin
- MCP tool
org_access_previewon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
scopeobjectrequired6 fields
entitiesstring[]Up to 100 items.
unitsstring[]Up to 200 items.
locationsstring[]Up to 200 items.
reporting_linebooleanDefault
false.peoplestring[]Up to 500 items.
groupsstring[]Up to 20 items.
areasobject
Returns
everyonebooleanrequiredcountintegerrequiredpeopleobject[]required2 fields
idstringrequirednamestringrequired
warningsstring[]requiredGroups that can't scope a role with these areas (saving the role is refused).
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/access.preview \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"scope":{"groups":["g1"]},"areas":{"people":"view"}}'const res = await fetch('https://api.bizisy.com/v1/org/access.preview', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"scope": {
"groups": [
"g1"
]
},
"areas": {
"people": "view"
}
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/access.preview",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"scope": {
"groups": [
"g1",
],
},
"areas": {
"people": "view",
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"everyone": false,
"count": 2,
"people": [
{
"id": "p2",
"name": "Tomás Silva"
},
{
"id": "p4",
"name": "Lukas Weber"
}
],
"warnings": []
}
}Preview a role on one person#
POST/v1/org/access.preview_personRead
For owners and admins in Settings → Roles: one person's record as a role would see it — a built-in role (hr, viewer, member) or a custom role as given (areas, scope, machine_sensitive, external) — and what the role may do for them. through: app (signed in) or ai (an API key or AI app, which never reads private or pay details unless the role allows it). The holder is nobody, so "reporting line" covers no one, exactly like the role editor's count. Read-only; nothing is saved. In the app only.
- Web app only
- Refused for API keys and connected apps. Previewing a role is for owners and admins signed in to Bizisy.
- MCP tool
org_access_preview_personon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
person_idstringrequiredroleobjectrequired2 fields (one of several shapes)
Option 1
built_in"hr" | "viewer" | "member"required
Option 2
customobjectrequired4 fields
areasobjectDefault
{}.13 fields
people"none" | "view" | "propose" | "edit" | "approve"requiredprivate"none" | "view" | "propose" | "edit" | "approve"requiredpay"none" | "view" | "propose" | "edit" | "approve"requireddocuments"none" | "view" | "propose" | "edit" | "approve"requiredchecklists"none" | "view" | "propose" | "edit" | "approve"requiredpositions"none" | "view" | "propose" | "edit" | "approve"requiredpay_equity"none" | "view" | "propose" | "edit" | "approve"requiredpayroll"none" | "view" | "propose" | "edit" | "approve"requiredstructure"none" | "view" | "propose" | "edit" | "approve"requiredactivity"none" | "view" | "propose" | "edit" | "approve"requiredtime_off"none" | "view" | "propose" | "edit" | "approve"requiredsetup"none" | "view" | "propose" | "edit" | "approve"requiredsurveys"none" | "view" | "propose" | "edit" | "approve"required
scopeobjectrequired6 fields
entitiesstring[]1–64 characters. Up to 100 items.
unitsstring[]1–64 characters. Up to 200 items.
locationsstring[]1–64 characters. Up to 200 items.
reporting_linebooleanDefault
false.peoplestring[]1–64 characters. Up to 500 items.
groupsstring[]1–64 characters. Up to 20 items.
machine_sensitivebooleanDefault
false.externalbooleanDefault
false.
through"app" | "ai"Default
"app".
Returns
visiblebooleanrequiredWhether the role can open this person at all (outsiders see only the people their role covers).
coveredbooleanrequiredA custom role: whether its scope covers this person (built-in roles: true).
tiers"public" | "private" | "job" | "pay"[]requiredWhat it sees: public (name, photo, work email), job, private, pay.
personobject | nullrequiredThe record shaped as the role sees it (null when it cannot open the person).
35 fields
idstringrequirednamestringrequiredgiven_namestringrequiredfamily_namestringrequiredpreferred_namestring | nullrequiredwork_emailstringrequiredtitlestring | nullrequiredstatus"invited" | "pre_hire" | "active" | "terminated" | "none"requiredinvited: waiting for their details (names, title, start date), not employed yet; pre_hire: starts later; active; terminated: has left; none: no job.
start_datestring | nullrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
invitedbooleanrequiredhas_loginbooleanrequiredphoto_urlstring | nullrequiredpronounsstring | nullrequiredwork_phonestring | nullrequiredpersonal_emailstring | nullrequiredpersonal_phonestring | nullrequiredaddressobject | nullrequired5 fields
line1stringrequiredline2stringcitystringrequiredpostal_codestringcountrystringrequired
birthdaystring | nullrequiredsex"female" | "male" | "another" | "undisclosed"requiredFor 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[] | nullrequired3 fields
namestringrequiredrelationshipstringrequiredphonestringrequired
tax_idstring | nullrequiredsocial_security_numberstring | nullrequiredibanstring | nullrequiredcustomobject[]required7 fields
keystringrequiredlabelstringrequiredtypestring (enum)requiredOne of:
text,number,date,select,boolean,file,person,table.tier"public" | "job" | "private"requiredvaluestring | number | boolean | object[]requiredFor type file: the document id (download it with
documents_downloadordocuments_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 inorg_fields_list).fileobject | nullType file only: the file, or null when none is attached.
4 fields
namestring | nullrequiredThe file name; null over an API key or MCP for someone else's file.
sizeintegerrequiredcontent_typestringrequiredpreviewablebooleanrequiredThe web app can show it (PDF, PNG, JPEG, WebP).
personobject | nullType person only: who it names (null when not set, or not someone you may see).
4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
jobobject | nullrequired23 fields
idstringrequiredvalid_fromstringrequiredvalid_tostring | nullrequiredtitlestringrequiredThe job title as the catalog names it now (reports and grouping use this).
title_idstring | nullrequiredThe catalog title (
org_titles_list); null while not in the catalog yet.display_titlestring | nullrequiredA different title shown on the profile, chart and directory; null: the catalog title.
unitobject | nullrequired2 fields
idstringrequirednamestringrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
legal_entityobject | nullrequired2 fields
idstringrequirednamestringrequired
employment_type"full_time" | "part_time" | "contractor" | "intern"requiredftenumberrequiredreasonstringrequiredend_reasonstring | nullrequiredleaving_typestring (enum)requiredWhy the employment ended (structured); null: not recorded or still employed.
One of:
resignation,retirement,dismissal,redundancy,end_of_contract,mutual_agreement,death,other.toldboolean | nullrequiredWith 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_toldor the day passes. null on other rows.contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredcontract_end_datestring | nullrequiredprobation_end_datestring | nullrequiredweekly_hoursnumber | nullrequirednotice_period_daysinteger | nullrequiredcustomobject[]requiredJob 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
keystringrequiredlabelstringrequiredtypestring (enum)requiredOne of:
text,number,date,select,boolean,file,person,table.tier"public" | "job" | "private"requiredvaluestring | number | boolean | object[]requiredFor type file: the document id (download it with
documents_downloadordocuments_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 inorg_fields_list).fileobject | nullType file only: the file, or null when none is attached.
4 fields
namestring | nullrequiredThe file name; null over an API key or MCP for someone else's file.
sizeintegerrequiredcontent_typestringrequiredpreviewablebooleanrequiredThe web app can show it (PDF, PNG, JPEG, WebP).
personobject | nullType person only: who it names (null when not set, or not someone you may see).
4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
regrettedboolean | nullPrivate (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[] | nullrequired23 fields
idstringrequiredvalid_fromstringrequiredvalid_tostring | nullrequiredtitlestringrequiredThe job title as the catalog names it now (reports and grouping use this).
title_idstring | nullrequiredThe catalog title (
org_titles_list); null while not in the catalog yet.display_titlestring | nullrequiredA different title shown on the profile, chart and directory; null: the catalog title.
unitobject | nullrequired2 fields
idstringrequirednamestringrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
legal_entityobject | nullrequired2 fields
idstringrequirednamestringrequired
employment_type"full_time" | "part_time" | "contractor" | "intern"requiredftenumberrequiredreasonstringrequiredend_reasonstring | nullrequiredleaving_typestring (enum)requiredWhy the employment ended (structured); null: not recorded or still employed.
One of:
resignation,retirement,dismissal,redundancy,end_of_contract,mutual_agreement,death,other.toldboolean | nullrequiredWith 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_toldor the day passes. null on other rows.contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredcontract_end_datestring | nullrequiredprobation_end_datestring | nullrequiredweekly_hoursnumber | nullrequirednotice_period_daysinteger | nullrequiredcustomobject[]requiredJob 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
keystringrequiredlabelstringrequiredtypestring (enum)requiredOne of:
text,number,date,select,boolean,file,person,table.tier"public" | "job" | "private"requiredvaluestring | number | boolean | object[]requiredFor type file: the document id (download it with
documents_downloadordocuments_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 inorg_fields_list).fileobject | nullType file only: the file, or null when none is attached.
4 fields
namestring | nullrequiredThe file name; null over an API key or MCP for someone else's file.
sizeintegerrequiredcontent_typestringrequiredpreviewablebooleanrequiredThe web app can show it (PDF, PNG, JPEG, WebP).
personobject | nullType person only: who it names (null when not set, or not someone you may see).
4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
regrettedboolean | nullPrivate (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[]required4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
visible_tiers"public" | "private" | "job" | "pay"[]requiredplannedobject | nullrequiredWhile invited (status invited): the job details known so far (job tier; null otherwise or when not visible).
14 fields
titlestring | nullrequiredtitle_idstring | nullrequiredstart_datestring | nullrequiredunitobject | nullrequired2 fields
idstringrequirednamestringrequired
managerobject | nullrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
locationobject | nullrequired2 fields
idstringrequirednamestringrequired
legal_entityobject | nullrequired2 fields
idstringrequirednamestringrequired
employment_type"full_time" | "part_time" | "contractor" | "intern"requiredftenumber | nullrequiredcontract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"requiredcontract_end_datestring | nullrequiredprobation_end_datestring | nullrequiredweekly_hoursnumber | nullrequirednotice_period_daysinteger | nullrequired
missing"given_name" | "family_name" | "title" | "start_date"[]requiredWhile invited: what is still needed to register them (given_name, family_name, title, start_date); [] otherwise.
dotted_managersobject[]requiredDotted-line managers today (spec structure-over-time D10): they see job details, never approve.
4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
dotted_reportsobject[]requiredPeople this person has a dotted line to today.
4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
canobject[]requiredThe areas the role grants for this person, each at its level (people-scoped areas only when covered; company-wide areas always). Through ai, machine_limit says what those actions still keep from API keys and AI apps.
4 fields
areastring (enum)requiredOne of:
people,private,pay,documents,checklists,positions,pay_equity,payroll,structure,activity,time_off,setup,surveys.level"none" | "view" | "propose" | "edit" | "approve"requiredcompany_widebooleanrequiredmachine_limitstring | nullrequiredthrough: ai only — what the real actions in this area still keep from API keys and AI apps (null: nothing more).
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/access.preview_person \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"person_id": "p2",
"role": {
"custom": {
"areas": {
"people": "view",
"pay": "view"
},
"scope": {
"entities": [],
"units": [
"u2"
],
"locations": [],
"reporting_line": false,
"people": [],
"groups": []
},
"machine_sensitive": false,
"external": true
}
},
"through": "ai"
}'const res = await fetch('https://api.bizisy.com/v1/org/access.preview_person', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"person_id": "p2",
"role": {
"custom": {
"areas": {
"people": "view",
"pay": "view"
},
"scope": {
"entities": [],
"units": [
"u2"
],
"locations": [],
"reporting_line": false,
"people": [],
"groups": []
},
"machine_sensitive": false,
"external": true
}
},
"through": "ai"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/access.preview_person",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"person_id": "p2",
"role": {
"custom": {
"areas": {
"people": "view",
"pay": "view",
},
"scope": {
"entities": [],
"units": [
"u2",
],
"locations": [],
"reporting_line": False,
"people": [],
"groups": [],
},
"machine_sensitive": False,
"external": True,
},
},
"through": "ai",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"visible": true,
"covered": true,
"tiers": [
"public",
"job"
],
"person": null,
"can": [
{
"area": "people",
"level": "view",
"company_wide": false,
"machine_limit": "Approving or rejecting requests needs a person signed in."
}
]
}
}Give an outsider access#
POST/v1/org/outsiders.inviteWrite
Gives someone who does not work for the company (a payroll bureau, an accountant, an auditor, a recruiter) access with a custom role (role_id from platform_roles_list) until a date (access_until, YYYY-MM-DD, after today and at most three years ahead): adds their contact card (name, firm, work email; no job: never in the directory, headcount, billing or reports) and emails them a sign-in link (url once, in the app). They see only the people their role covers. Outsiders are not charged; at most 25 at a time. Owners and admins, in the web app only.
- Web app only
- Refused for API keys and connected apps. Outside access is given in the app only.
- MCP tool
org_outsiders_inviteon HR Assistant- Preview
?dry_run=trueruns 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_namestringrequired1–100 characters.
family_namestringrequired1–100 characters.
organizationstringTheir firm, e.g. "Contas & Cia".
Up to 120 characters.
work_emailanyrequiredrole_idstringrequiredaccess_untilstringrequiredPattern
^\d{4}-\d{2}-\d{2}$.
Returns
person_idstringrequiredinvite_idstringrequiredurlstring | nullrequiredexpires_atstringrequiredaccess_untilstringrequiredemailobjectrequired3 fields
status"sent" | "failed" | "skipped"requiredmessagestringrequiredreason"rate_limited"
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/outsiders.invite \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"given_name": "Olga",
"family_name": "Santos",
"organization": "Contas & Cia",
"work_email": "olga@contas.test",
"role_id": "r1",
"access_until": "2027-09-30"
}'const res = await fetch('https://api.bizisy.com/v1/org/outsiders.invite', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"given_name": "Olga",
"family_name": "Santos",
"organization": "Contas & Cia",
"work_email": "olga@contas.test",
"role_id": "r1",
"access_until": "2027-09-30"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/outsiders.invite",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"given_name": "Olga",
"family_name": "Santos",
"organization": "Contas & Cia",
"work_email": "olga@contas.test",
"role_id": "r1",
"access_until": "2027-09-30",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"person_id": "p9",
"invite_id": "i2",
"url": "https://acme.bizisy.com/invite#token=tok",
"expires_at": "2026-10-22T10:00:00.000Z",
"access_until": "2027-09-30",
"email": {
"status": "sent",
"message": "We emailed the link to olga@contas.test."
}
}
}Something missing or wrong on this page? Write to hello@bizisy.com.