Skip to content

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_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • groupsobject[]required
    10 fields
    • idstringrequired
    • namestringrequired
    • descriptionstring | nullrequired
    • status"current" | "active" | "pre_hire" | "terminated" | "all"required
    • conditionsobject[]required
      4 fields
      • fieldstringrequired
      • opstring (enum)required

        One of: in, not_in, is, is_not, contains, gte, lte, is_set, is_empty.

      • valuesstring | number | boolean[]required
      • include_subunitsboolean
    • usesobjectrequired
      3 fields
      • jobbooleanrequired

        Some condition uses job details.

      • privatebooleanrequired

        Some condition uses a private custom field: the group is sensitive.

      • architecturebooleanrequired

        Some condition uses job families or levels.

    • sensitivebooleanrequired
    • member_countintegerrequired

      Members today as you see them: people matching only through data you may not see are not counted.

    • used_byobject | nullrequired

      Roles and checklist templates using it (owners, admins and HR; null for others).

      2 fields
      • rolesobject[]required
        2 fields
        • idstringrequired
        • namestringrequired
      • checklistsobject[]required
        2 fields
        • idstringrequired
        • namestringrequired
    • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/groups.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "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_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • group_idstringrequired

Returns

11 fields
  • idstringrequired
  • namestringrequired
  • descriptionstring | nullrequired
  • status"current" | "active" | "pre_hire" | "terminated" | "all"required
  • conditionsobject[]required
    4 fields
    • fieldstringrequired
    • opstring (enum)required

      One of: in, not_in, is, is_not, contains, gte, lte, is_set, is_empty.

    • valuesstring | number | boolean[]required
    • include_subunitsboolean
  • usesobjectrequired
    3 fields
    • jobbooleanrequired

      Some condition uses job details.

    • privatebooleanrequired

      Some condition uses a private custom field: the group is sensitive.

    • architecturebooleanrequired

      Some condition uses job families or levels.

  • sensitivebooleanrequired
  • member_countintegerrequired

    Members today as you see them: people matching only through data you may not see are not counted.

  • used_byobject | nullrequired

    Roles and checklist templates using it (owners, admins and HR; null for others).

    2 fields
    • rolesobject[]required
      2 fields
      • idstringrequired
      • namestringrequired
    • checklistsobject[]required
      2 fields
      • idstringrequired
      • namestringrequired
  • updated_atstringrequired
  • membersobject[]required
    3 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/groups.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"group_id":"g1"}'
Response
{
  "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_preview on HR Assistant
Method
POST with a JSON body, or GET with 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
    • fieldstringrequired

      A 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)required

      One of: in, not_in, is, is_not, contains, gte, lte, is_set, is_empty.

    • valuesstring | number | boolean[]

      Up to 200 items.

    • include_subunitsboolean

      unit only: teams below each chosen team count too (default true).

Returns

  • countintegerrequired
  • peopleobject[]required
    3 fields
    • idstringrequired
    • namestringrequired
    • titlestring | nullrequired
  • usesobjectrequired
    3 fields
    • jobbooleanrequired

      Some condition uses job details.

    • privatebooleanrequired

      Some condition uses a private custom field: the group is sensitive.

    • architecturebooleanrequired

      Some condition uses job families or levels.

  • sensitivebooleanrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
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": []
    }
  ]
}'
Response
{
  "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_create 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

  • namestringrequired

    1–60 characters.

  • descriptionstring | null

    Up 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
    • fieldstringrequired

      A 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)required

      One of: in, not_in, is, is_not, contains, gte, lte, is_set, is_empty.

    • valuesstring | number | boolean[]

      Up to 200 items.

    • include_subunitsboolean

      unit only: teams below each chosen team count too (default true).

Returns

  • idstringrequired
  • namestringrequired
  • member_countintegerrequired

    Members today as you see them.

  • sensitivebooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
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
      ]
    }
  ]
}'
Response
{
  "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_update 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

  • group_idstringrequired
  • namestring

    1–60 characters.

  • descriptionstring | null

    Up to 300 characters.

  • status"current" | "active" | "pre_hire" | "terminated" | "all"
  • conditionsobject[]

    Up to 20 items.

    4 fields
    • fieldstringrequired

      A 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)required

      One of: in, not_in, is, is_not, contains, gte, lte, is_set, is_empty.

    • valuesstring | number | boolean[]

      Up to 200 items.

    • include_subunitsboolean

      unit only: teams below each chosen team count too (default true).

Returns

  • idstringrequired
  • namestringrequired
  • member_countintegerrequired

    Members today as you see them.

  • sensitivebooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
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
      ]
    }
  ]
}'
Response
{
  "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_delete on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • group_idstringrequired

Returns

  • idstringrequired
  • deletedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
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"}'
Response
{
  "data": {
    "id": "g1",
    "deleted": true
  }
}

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

Developer docs