API reference
Saved groups
Named people criteria that update themselves: filter people and the org chart, scope custom roles, choose who gets a checklist.
6 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.
List saved groups#
POST/v1/org/groups.listRead
Lists the company's saved groups (Settings → Groups): named people criteria that update themselves, used to filter People and the org chart, scope custom roles and choose checklist audiences. Each has its criteria, uses (job, private, architecture), member_count and, for owners, admins and HR, used_by (roles and checklist templates). Members are counted today and as you see them: a condition on data you may not see for a person (job details of someone you do not manage, a private field) is not met for them, so a group never reveals who matches hidden data. Groups with a private field condition are sensitive: listed only to those who see private details (never over an API key or AI app unless the role allows it). Owners, admins, HR, viewers and custom roles (not outsiders).
- Who can call it
- Manage key any Manage role
- Keys and apps
- Groups with a private field are left out, and private fields never count for members.
- MCP tool
org_groups_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
groupsobject[]required10 fields
idstringrequirednamestringrequireddescriptionstring | nullrequiredstatus"current" | "active" | "pre_hire" | "terminated" | "all"requiredconditionsobject[]required4 fields
fieldstringrequiredopstring (enum)requiredOne of:
in,not_in,is,is_not,contains,gte,lte,is_set,is_empty.valuesstring | number | boolean[]requiredinclude_subunitsboolean
usesobjectrequired3 fields
jobbooleanrequiredSome condition uses job details.
privatebooleanrequiredSome condition uses a private custom field: the group is sensitive.
architecturebooleanrequiredSome condition uses job families or levels.
sensitivebooleanrequiredmember_countintegerrequiredMembers today as you see them: people matching only through data you may not see are not counted.
used_byobject | nullrequiredRoles and checklist templates using it (owners, admins and HR; null for others).
2 fields
rolesobject[]required2 fields
idstringrequirednamestringrequired
checklistsobject[]required2 fields
idstringrequirednamestringrequired
updated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/groups.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/org/groups.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
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/groups.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"groups": [
{
"id": "g1",
"name": "Lisbon on probation",
"description": "New joiners in Lisbon still on probation",
"status": "current",
"conditions": [
{
"field": "location",
"op": "in",
"values": [
"l1"
]
},
{
"field": "on_probation",
"op": "is",
"values": [
true
]
}
],
"uses": {
"job": true,
"private": false,
"architecture": false
},
"sensitive": false,
"member_count": 2,
"used_by": {
"roles": [],
"checklists": [
{
"id": "o1_onboarding",
"name": "Onboarding"
}
]
},
"updated_at": "2026-10-04T10:00:00.000Z"
}
]
}
}Get a saved group and its members#
POST/v1/org/groups.getRead
One saved group with its members today (the first 50 by name: id, name, title). Members are counted today and as you see them: a condition on data you may not see for a person (job details of someone you do not manage, a private field) is not met for them, so a group never reveals who matches hidden data. Same callers as org_groups_list.
- Who can call it
- Manage key any Manage role
- MCP tool
org_groups_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
group_idstringrequired
Returns
11 fields
idstringrequirednamestringrequireddescriptionstring | nullrequiredstatus"current" | "active" | "pre_hire" | "terminated" | "all"requiredconditionsobject[]required4 fields
fieldstringrequiredopstring (enum)requiredOne of:
in,not_in,is,is_not,contains,gte,lte,is_set,is_empty.valuesstring | number | boolean[]requiredinclude_subunitsboolean
usesobjectrequired3 fields
jobbooleanrequiredSome condition uses job details.
privatebooleanrequiredSome condition uses a private custom field: the group is sensitive.
architecturebooleanrequiredSome condition uses job families or levels.
sensitivebooleanrequiredmember_countintegerrequiredMembers today as you see them: people matching only through data you may not see are not counted.
used_byobject | nullrequiredRoles and checklist templates using it (owners, admins and HR; null for others).
2 fields
rolesobject[]required2 fields
idstringrequirednamestringrequired
checklistsobject[]required2 fields
idstringrequirednamestringrequired
updated_atstringrequiredmembersobject[]required3 fields
idstringrequirednamestringrequiredtitlestring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/groups.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"group_id":"g1"}'const res = await fetch('https://api.bizisy.com/v1/org/groups.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"group_id": "g1"
}),
});
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/groups.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"group_id": "g1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "g1",
"name": "Lisbon on probation",
"description": "New joiners in Lisbon still on probation",
"status": "current",
"conditions": [
{
"field": "location",
"op": "in",
"values": [
"l1"
]
},
{
"field": "on_probation",
"op": "is",
"values": [
true
]
}
],
"uses": {
"job": true,
"private": false,
"architecture": false
},
"sensitive": false,
"member_count": 2,
"used_by": {
"roles": [],
"checklists": [
{
"id": "o1_onboarding",
"name": "Onboarding"
}
]
},
"updated_at": "2026-10-04T10:00:00.000Z",
"members": [
{
"id": "p2",
"name": "Tomás Silva",
"title": "Software Engineer"
},
{
"id": "p4",
"name": "Lukas Weber",
"title": null
}
]
}
}Preview who criteria match#
POST/v1/org/groups.previewRead
Who these criteria match today, without saving (for the group editor and for an AI checking a sentence it turned into criteria): count and the first 50 by name. Fields (each condition {field, op, values}; values match any; all conditions must hold): unit (in/not_in team ids; include_subunits default true), location (in/not_in), legal_entity (in/not_in; job details), manager (in: direct reports of these people), title (in/not_in catalog ids; merged titles count), family and level (in/not_in; job architecture), is_manager (is [true|false]), started_within_days (lte [n]), employment_type and contract_type (in/not_in; job details), on_probation (is [true|false]; job details), probation_ends_within_days and contract_ends_within_days (lte [n]; job details), custom:<key> for a custom person field (select: is/is_not; yes/no: is; text: is/is_not/contains; number: is/is_not/gte/lte; date: is/gte/lte YYYY-MM-DD; any: is_set/is_empty with values []), with the field's tier. No leaving or pay conditions. Members are counted today and as you see them: a condition on data you may not see for a person (job details of someone you do not manage, a private field) is not met for them, so a group never reveals who matches hidden data. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_groups_previewon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
status"current" | "active" | "pre_hire" | "terminated" | "all"current (default: employed today or starting later), active (employed today), pre_hire (starting later), terminated (left) or all. Invited people are never members.
Default
"current".conditionsobject[]Up to 20 conditions; all must hold.
Up to 20 items.
4 fields
fieldstringrequiredA built-in field (unit, location, legal_entity, manager, title, family, level, is_manager, started_within_days, employment_type, contract_type, on_probation, probation_ends_within_days, contract_ends_within_days) or custom:<key> for a custom person field.
1–80 characters.
opstring (enum)requiredOne of:
in,not_in,is,is_not,contains,gte,lte,is_set,is_empty.valuesstring | number | boolean[]Up to 200 items.
include_subunitsbooleanunit only: teams below each chosen team count too (default true).
Returns
countintegerrequiredpeopleobject[]required3 fields
idstringrequirednamestringrequiredtitlestring | nullrequired
usesobjectrequired3 fields
jobbooleanrequiredSome condition uses job details.
privatebooleanrequiredSome condition uses a private custom field: the group is sensitive.
architecturebooleanrequiredSome condition uses job families or levels.
sensitivebooleanrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/groups.preview \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"status": "all",
"conditions": [
{
"field": "unit",
"op": "in",
"values": [
"u2"
],
"include_subunits": false
},
{
"field": "custom:shirt",
"op": "is_set",
"values": []
}
]
}'const res = await fetch('https://api.bizisy.com/v1/org/groups.preview', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"status": "all",
"conditions": [
{
"field": "unit",
"op": "in",
"values": [
"u2"
],
"include_subunits": false
},
{
"field": "custom:shirt",
"op": "is_set",
"values": []
}
]
}),
});
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/groups.preview",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"status": "all",
"conditions": [
{
"field": "unit",
"op": "in",
"values": [
"u2",
],
"include_subunits": False,
},
{
"field": "custom:shirt",
"op": "is_set",
"values": [],
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"count": 2,
"people": [
{
"id": "p2",
"name": "Tomás Silva",
"title": "Software Engineer"
}
],
"uses": {
"job": true,
"private": false,
"architecture": false
},
"sensitive": false
}
}Save a group#
POST/v1/org/groups.createWrite
Saves a named group of people from criteria (name unique in the company, at most 60 characters; optional description; at most 100 groups). status: current (default), active, pre_hire, terminated or all. Fields (each condition {field, op, values}; values match any; all conditions must hold): unit (in/not_in team ids; include_subunits default true), location (in/not_in), legal_entity (in/not_in; job details), manager (in: direct reports of these people), title (in/not_in catalog ids; merged titles count), family and level (in/not_in; job architecture), is_manager (is [true|false]), started_within_days (lte [n]), employment_type and contract_type (in/not_in; job details), on_probation (is [true|false]; job details), probation_ends_within_days and contract_ends_within_days (lte [n]; job details), custom:<key> for a custom person field (select: is/is_not; yes/no: is; text: is/is_not/contains; number: is/is_not/gte/lte; date: is/gte/lte YYYY-MM-DD; any: is_set/is_empty with values []), with the field's tier. No leaving or pay conditions. To turn a sentence into a group: find ids with org_find (teams, locations, people) and org_titles_list, dry-run this action to show the user the member_count, then save. Members are counted today and as you see them: a condition on data you may not see for a person (job details of someone you do not manage, a private field) is not met for them, so a group never reveals who matches hidden data. Owners, admins and HR; never a custom role.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_groups_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
namestringrequired1–60 characters.
descriptionstring | nullUp to 300 characters.
status"current" | "active" | "pre_hire" | "terminated" | "all"current (default: employed today or starting later), active (employed today), pre_hire (starting later), terminated (left) or all. Invited people are never members.
Default
"current".conditionsobject[]Up to 20 conditions; all must hold.
Up to 20 items.
4 fields
fieldstringrequiredA built-in field (unit, location, legal_entity, manager, title, family, level, is_manager, started_within_days, employment_type, contract_type, on_probation, probation_ends_within_days, contract_ends_within_days) or custom:<key> for a custom person field.
1–80 characters.
opstring (enum)requiredOne of:
in,not_in,is,is_not,contains,gte,lte,is_set,is_empty.valuesstring | number | boolean[]Up to 200 items.
include_subunitsbooleanunit only: teams below each chosen team count too (default true).
Returns
idstringrequirednamestringrequiredmember_countintegerrequiredMembers today as you see them.
sensitivebooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/groups.create \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"name": "Engineering managers",
"description": "Leads in Engineering",
"status": "active",
"conditions": [
{
"field": "unit",
"op": "in",
"values": [
"u2"
]
},
{
"field": "is_manager",
"op": "is",
"values": [
true
]
}
]
}'const res = await fetch('https://api.bizisy.com/v1/org/groups.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"name": "Engineering managers",
"description": "Leads in Engineering",
"status": "active",
"conditions": [
{
"field": "unit",
"op": "in",
"values": [
"u2"
]
},
{
"field": "is_manager",
"op": "is",
"values": [
true
]
}
]
}),
});
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/groups.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"name": "Engineering managers",
"description": "Leads in Engineering",
"status": "active",
"conditions": [
{
"field": "unit",
"op": "in",
"values": [
"u2",
],
},
{
"field": "is_manager",
"op": "is",
"values": [
True,
],
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "g2",
"name": "Engineering managers",
"member_count": 2,
"sensitive": false
}
}Change a group#
POST/v1/org/groups.updateWrite
Changes a saved group: name, description, status or conditions (replaced whole). Everything using it follows at once (People filters, the chart, role scopes, checklist audiences). A group a custom role uses decides whom that role covers: only owners and admins change it, in the app (refused to API keys and AI apps); it can't gain a private field condition, nor job details or job families unless every role using it sees them. A group a checklist uses can't gain a private field condition. Fields (each condition {field, op, values}; values match any; all conditions must hold): unit (in/not_in team ids; include_subunits default true), location (in/not_in), legal_entity (in/not_in; job details), manager (in: direct reports of these people), title (in/not_in catalog ids; merged titles count), family and level (in/not_in; job architecture), is_manager (is [true|false]), started_within_days (lte [n]), employment_type and contract_type (in/not_in; job details), on_probation (is [true|false]; job details), probation_ends_within_days and contract_ends_within_days (lte [n]; job details), custom:<key> for a custom person field (select: is/is_not; yes/no: is; text: is/is_not/contains; number: is/is_not/gte/lte; date: is/gte/lte YYYY-MM-DD; any: is_set/is_empty with values []), with the field's tier. No leaving or pay conditions. Owners, admins and HR; never a custom role.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- A group a custom role uses decides whom the role covers: changing it needs an owner or admin signed in to Bizisy.
- MCP tool
org_groups_updateon 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
group_idstringrequirednamestring1–60 characters.
descriptionstring | nullUp to 300 characters.
status"current" | "active" | "pre_hire" | "terminated" | "all"conditionsobject[]Up to 20 items.
4 fields
fieldstringrequiredA built-in field (unit, location, legal_entity, manager, title, family, level, is_manager, started_within_days, employment_type, contract_type, on_probation, probation_ends_within_days, contract_ends_within_days) or custom:<key> for a custom person field.
1–80 characters.
opstring (enum)requiredOne of:
in,not_in,is,is_not,contains,gte,lte,is_set,is_empty.valuesstring | number | boolean[]Up to 200 items.
include_subunitsbooleanunit only: teams below each chosen team count too (default true).
Returns
idstringrequirednamestringrequiredmember_countintegerrequiredMembers today as you see them.
sensitivebooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/groups.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"group_id": "g1",
"status": "all",
"conditions": [
{
"field": "started_within_days",
"op": "lte",
"values": [
90
]
}
]
}'const res = await fetch('https://api.bizisy.com/v1/org/groups.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"group_id": "g1",
"status": "all",
"conditions": [
{
"field": "started_within_days",
"op": "lte",
"values": [
90
]
}
]
}),
});
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/groups.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"group_id": "g1",
"status": "all",
"conditions": [
{
"field": "started_within_days",
"op": "lte",
"values": [
90,
],
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "g1",
"name": "Lisbon probation",
"member_count": 2,
"sensitive": false
}
}Delete a group#
POST/v1/org/groups.deleteWrite
Deletes a saved group. Refused while a custom role or a checklist template (archived ones too) uses it: the error names them; remove the group there first. Nothing about people changes. Owners, admins and HR; never a custom role.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_groups_deleteon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
group_idstringrequired
Returns
idstringrequireddeletedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/groups.delete \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"group_id":"g1"}'const res = await fetch('https://api.bizisy.com/v1/org/groups.delete', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"group_id": "g1"
}),
});
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/groups.delete",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"group_id": "g1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "g1",
"deleted": true
}
}Something missing or wrong on this page? Write to hello@bizisy.com.