API reference
Directory sync
Google Workspace and Microsoft Entra: the connection, importing people once, what each sync sends (new accounts, changes, suspensions) and confirming new accounts. Connecting and confirming happen in the web app.
13 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.
Directory sync status#
POST/v1/org/directory.statusRead
Google Workspace and Microsoft Entra directory sync (spec directory-sync): for each provider, whether this server offers it (available), the connection (status, the directory's domain or name, settings: create (confirm: HR confirms each new account; auto: created days_before the start), days_before, suspend leavers, team → group mappings) and counts (linked accounts, excluded, administrator accounts never touched, changes the next run sends, creations or reactivations waiting for HR, failures). Owners, admins and HR; never custom roles.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_directory_statuson HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
providersobject[]required5 fields
provider"google" | "entra"requirednamestringrequiredavailablebooleanrequiredThe server can connect this provider (its OAuth app is set up); false: not available yet.
connectionobject | nullrequired9 fields
status"pending" | "connected" | "error"requiredlabelstring | nullrequireddomainsstring[]requiredconnected_atstring | nullrequirederrorstring | nullrequiredsetup_completebooleanrequiredFalse from a first connect until an owner or admin finishes the setup (Start syncing in the connect wizard, or settings_update setup_complete: true); nothing is created, changed or suspended until then.
failureobject | nullrequiredWhy the last attempt to connect failed, until one succeeds: session, not_admin, taken, denied, scopes (not every permission allowed), refused (the directory refused Bizisy, e.g. an admin console policy), propagating (Microsoft has not applied the consent yet: try again in a few minutes), failed.
2 fields
reasonstring (enum)requiredOne of:
session,not_admin,taken,denied,scopes,refused,propagating,failed.atstringrequired
foundobject | nullrequiredAccounts seen in the directory when it was connected (more: there are more than count). Nothing is imported until someone imports or links people.
2 fields
countintegerrequiredmorebooleanrequired
settingsobjectrequired5 fields
create"confirm" | "auto"requireddays_beforeintegerrequiredsuspendbooleanrequiredorg_unitstring | nullrequiredGoogle: the organizational unit path new accounts go to (null: the root). Always null for Entra.
groupsobject[]required4 fields
unit_idstringrequiredunit_namestring | nullrequiredgroup_idstringrequiredgroup_namestringrequired
countsobjectrequired6 fields
linkedintegerrequiredexcludedintegerrequiredadminintegerrequiredpendingintegerrequiredChanges the next run sends (creations waiting for HR not included).
waiting_for_confirmintegerrequiredfailedintegerrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/directory.status \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/org/directory.status', {
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/directory.status",
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": {
"providers": [
{
"provider": "google",
"name": "Google Workspace",
"available": true,
"connection": {
"status": "connected",
"label": "acme.test",
"domains": [
"acme.test"
],
"connected_at": "2026-10-01T10:00:00.000Z",
"error": null,
"setup_complete": true,
"failure": null,
"found": {
"count": 14,
"more": false
},
"settings": {
"create": "confirm",
"days_before": 3,
"org_unit": null,
"suspend": true,
"groups": [
{
"unit_id": "u2",
"unit_name": "Engineering",
"group_id": "g1",
"group_name": "Engineering"
}
]
}
},
"counts": {
"linked": 12,
"excluded": 1,
"admin": 1,
"pending": 2,
"waiting_for_confirm": 1,
"failed": 0
}
},
{
"provider": "entra",
"name": "Microsoft Entra",
"available": false,
"connection": null,
"counts": {
"linked": 0,
"excluded": 0,
"admin": 0,
"pending": 0,
"waiting_for_confirm": 0,
"failed": 0
}
}
]
}
}Connect a directory#
POST/v1/org/directory.connectWrite
Starts connecting Google Workspace or Microsoft Entra: returns the address where an administrator of that directory grants Bizisy access (it expires in 15 minutes). Owners and admins, in the app only.
- Web app only
- Refused for API keys and connected apps. An owner or admin connects a directory in the app (Integrations → Google Workspace or Microsoft 365 → Directory sync).
- MCP tool
org_directory_connecton 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
provider"google" | "entra"required
Returns
urlstringrequiredexpires_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/directory.connect \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"provider":"google"}'const res = await fetch('https://api.bizisy.com/v1/org/directory.connect', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"provider": "google"
}),
});
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/directory.connect",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"provider": "google",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"url": "https://accounts.google.com/o/oauth2/v2/auth?state=x",
"expires_at": "2026-10-09T10:15:00.000Z"
}
}Disconnect a directory#
POST/v1/org/directory.disconnectDestructive
Stops directory sync with Google Workspace or Microsoft Entra: forgets the connection, its links to accounts and any first password not seen yet, and hands Google its access back. Accounts in the directory stay as they are. For Microsoft Entra, next_step says how an admin removes the app in Microsoft too. Owners and admins, in the app only.
- Web app only
- Refused for API keys and connected apps. Disconnecting happens in the app.
- MCP tool
org_directory_disconnecton HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
provider"google" | "entra"required
Returns
provider"google" | "entra"requireddisconnectedtruerequirednext_stepstring | nullrequiredWhat an admin of the directory does to end Bizisy's access there too (Microsoft Entra); null when Bizisy did it.
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/directory.disconnect \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"provider":"entra"}'const res = await fetch('https://api.bizisy.com/v1/org/directory.disconnect', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"provider": "entra"
}),
});
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/directory.disconnect",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"provider": "entra",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"provider": "entra",
"disconnected": true,
"next_step": "Bizisy no longer uses its access. To remove it in Microsoft too, an administrator deletes \"Bizisy directory sync\" in the Microsoft Entra admin center → Enterprise applications."
}
}Change directory sync settings#
POST/v1/org/directory.settings.updateWrite
Changes how a connected directory is kept in step: create (confirm: HR confirms each new account, the default; auto: accounts are created days_before the start without a click), days_before (0–14), suspend (suspend a leaver's account the day after their last day; default true), groups (team → directory group: [{unit_id, group_id, group_name}], at most 100; membership follows each person's team today), org_unit (Google only: the organizational unit path new accounts go to, as in the Admin console, e.g. "/Employees"; null: the root), setup_complete (true: finishes the connect wizard's setup; until then nothing is sent). Send only what changes. Owners and admins, in the app only.
- Web app only
- Refused for API keys and connected apps. Directory sync settings change in the app only.
- MCP tool
org_directory_settings_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
provider"google" | "entra"requiredcreate"confirm" | "auto"days_beforeintegerFrom 0 to 14.
suspendbooleangroupsobject[]Up to 100 items.
3 fields
unit_idstringrequiredgroup_idstringrequired1–200 characters.
group_namestringrequired1–200 characters.
org_unitstring | nullPattern
^\/[^\n\r]{0,499}$.setup_completetrue
Returns
provider"google" | "entra"requiredsettingsobjectrequired5 fields
create"confirm" | "auto"requireddays_beforeintegerrequiredsuspendbooleanrequiredorg_unitstring | nullrequiredgroupsobject[]required3 fields
unit_idstringrequiredgroup_idstringrequiredgroup_namestringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/directory.settings.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"provider": "google",
"create": "auto",
"days_before": 5,
"suspend": true,
"org_unit": "/Employees",
"setup_complete": true,
"groups": [
{
"unit_id": "u2",
"group_id": "g1",
"group_name": "Engineering"
}
]
}'const res = await fetch('https://api.bizisy.com/v1/org/directory.settings.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"provider": "google",
"create": "auto",
"days_before": 5,
"suspend": true,
"org_unit": "/Employees",
"setup_complete": true,
"groups": [
{
"unit_id": "u2",
"group_id": "g1",
"group_name": "Engineering"
}
]
}),
});
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/directory.settings.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"provider": "google",
"create": "auto",
"days_before": 5,
"suspend": True,
"org_unit": "/Employees",
"setup_complete": True,
"groups": [
{
"unit_id": "u2",
"group_id": "g1",
"group_name": "Engineering",
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"provider": "google",
"settings": {
"create": "auto",
"days_before": 5,
"suspend": true,
"org_unit": "/Employees",
"groups": [
{
"unit_id": "u2",
"group_id": "g1",
"group_name": "Engineering"
}
]
}
}
}Groups in a connected directory#
POST/v1/org/directory.groupsRead
Lists groups of a connected directory (q filters by name; at most 100), to map teams to groups (org_directory_settings_update groups). Owners and admins.
- Who can call it
- Manage key owner admin
- MCP tool
org_directory_groupson HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
provider"google" | "entra"requiredqstringUp to 100 characters.
Returns
groupsobject[]required3 fields
idstringrequirednamestringrequiredemailstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/directory.groups \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"provider":"google","q":"eng"}'const res = await fetch('https://api.bizisy.com/v1/org/directory.groups', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"provider": "google",
"q": "eng"
}),
});
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/directory.groups",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"provider": "google",
"q": "eng",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"groups": [
{
"id": "g1",
"name": "Engineering",
"email": "eng@acme.test"
}
]
}
}Accounts in a connected directory#
POST/v1/org/directory.usersRead
Lists accounts of a connected directory for the one-time import (q searches email and name; page with page_token): each with its email, name, title, department, whether it is suspended or an administrator, and the person in Bizisy with the same work email (match.linked: already linked). Owners, admins and HR; never custom roles.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_directory_userson HR Assistant- Method
POSTwith a JSON body only (an input field carries a secret)
Input
provider"google" | "entra"requiredqstringUp to 100 characters.
page_tokenstringUp to 500 characters.
Returns
usersobject[]required8 fields
account_idstringrequiredemailstringrequirednamestringrequiredtitlestring | nullrequireddepartmentstring | nullrequiredsuspendedbooleanrequiredadminbooleanrequiredmatchobject | nullrequiredThe person in Bizisy with this work email; linked: already linked to this account.
3 fields
person_idstringrequirednamestringrequiredlinkedbooleanrequired
next_page_tokenstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/directory.users \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"provider":"google","q":"rita","page_token":"p2"}'const res = await fetch('https://api.bizisy.com/v1/org/directory.users', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"provider": "google",
"q": "rita",
"page_token": "p2"
}),
});
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/directory.users",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"provider": "google",
"q": "rita",
"page_token": "p2",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"users": [
{
"account_id": "a1",
"email": "rita@acme.test",
"name": "Rita Lima",
"title": "Designer",
"department": "Product",
"suspended": false,
"admin": false,
"match": {
"person_id": "p3",
"name": "Rita Lima",
"linked": false
}
}
],
"next_page_token": null
}
}Import people from a directory#
POST/v1/org/directory.importWrite
One-time import from a connected directory (spec directory-sync D2): for each chosen account (account_ids from org_directory_users, at most 200), a person with the same work email is linked to it, and anyone else is invited by email (their name and title from the directory, their team when a team has the directory's department name, their manager when that manager's account is linked); send: now (default) or none, role for their sign-in. People in Bizisy are never changed; administrator accounts are linked but never touched by the sync. Owners, admins and HR, in the app only.
- Web app only
- Refused for API keys and connected apps. The one-time import runs in the app.
- MCP tool
org_directory_importon 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
provider"google" | "entra"requiredaccount_idsstring[]required1–200 characters. 1–200 items.
send"now" | "none"Default
"now".role"member" | "viewer" | "hr" | "admin"
Returns
linkedintegerrequiredinvitedintegerrequiredskippedobject[]required2 fields
account_idstringrequiredreasonstringrequired
departments_without_teamstring[]requiredDirectory departments with no team of that name (their people came in without a team).
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/directory.import \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"provider": "google",
"account_ids": [
"a1",
"a2"
],
"send": "none",
"role": "member"
}'const res = await fetch('https://api.bizisy.com/v1/org/directory.import', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"provider": "google",
"account_ids": [
"a1",
"a2"
],
"send": "none",
"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/directory.import",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"provider": "google",
"account_ids": [
"a1",
"a2",
],
"send": "none",
"role": "member",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"linked": 1,
"invited": 1,
"skipped": [],
"departments_without_team": [
"Legal"
]
}
}Link a person to a directory account#
POST/v1/org/directory.linkWrite
Links a person to an account of a connected directory (account_id from org_directory_users), or unlinks them (account_id null). The account's email must be the person's work email; otherwise only an owner or admin links it, with confirm_mismatch true after checking it is theirs. The next run then sends what Bizisy has differently (names, title, team, manager), never earlier changes; a suspension right after a link waits for a person. Owners, admins and HR, in the app only.
- Web app only
- Refused for API keys and connected apps. Linking a person to an account happens in the app.
- MCP tool
org_directory_linkon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
provider"google" | "entra"requiredperson_idstringrequiredaccount_idstring | nullrequired1–200 characters.
confirm_mismatchbooleanOwners and admins: link an account whose email is not the person's work email (checked by you to be theirs).
Returns
person_idstringrequiredaccount_emailstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/directory.link \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"provider": "google",
"person_id": "p1",
"account_id": "a2",
"confirm_mismatch": true
}'const res = await fetch('https://api.bizisy.com/v1/org/directory.link', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"provider": "google",
"person_id": "p1",
"account_id": "a2",
"confirm_mismatch": 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/directory.link",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"provider": "google",
"person_id": "p1",
"account_id": "a2",
"confirm_mismatch": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"person_id": "p1",
"account_email": "ana@acme.test"
}
}Keep a person out of directory sync#
POST/v1/org/directory.excludeWrite
Excludes a person from directory sync (excluded true: their account is never created, changed or suspended by Bizisy) or includes them again. Owners, admins and HR, in the app only.
- Web app only
- Refused for API keys and connected apps. Excluding someone from directory sync happens in the app.
- MCP tool
org_directory_excludeon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
provider"google" | "entra"requiredperson_idstringrequiredexcludedbooleanrequired
Returns
person_idstringrequiredexcludedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/directory.exclude \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"provider":"google","person_id":"p1","excluded":true}'const res = await fetch('https://api.bizisy.com/v1/org/directory.exclude', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"provider": "google",
"person_id": "p1",
"excluded": 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/directory.exclude",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"provider": "google",
"person_id": "p1",
"excluded": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"person_id": "p1",
"excluded": true
}
}Preview directory sync#
POST/v1/org/directory.previewRead
What the next run sends to a connected directory (a dry run: nothing is sent): suspensions of leavers, new accounts (waiting_for_confirm: HR confirms them in Bizisy), reactivations of rehires, and changes (fields: given_name, family_name, title, department, manager_id, groups), with each last error. Owners, admins and HR; never custom roles.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_directory_previewon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
provider"google" | "entra"required
Returns
itemsobject[]required10 fields
kind"create" | "update" | "suspend" | "reactivate"requiredpersonobjectrequired4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredphoto_urlstring | nullrequired
emailstringrequiredfieldsstring[]requiredwaiting_for_confirmbooleanrequiredstart_datestring | nullrequiredlast_errorstring | nullrequiredfailuresintegerrequiredheld"new_link" | "many"requiredsuspend waiting for a person: new_link (the first change since the account was linked: check it is the right account; owners, admins or HR confirm), many (many suspensions at once: owners or admins confirm each).
password_tostring | nullrequiredcreate: the personal email the first password goes to as a one-time link; null: HR hands it over (
org_directory_reveal_password).
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/directory.preview \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"provider":"google"}'const res = await fetch('https://api.bizisy.com/v1/org/directory.preview', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"provider": "google"
}),
});
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/directory.preview",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"provider": "google",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"items": [
{
"kind": "create",
"person": {
"id": "p2",
"name": "Rui Costa",
"title": "CTO",
"photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
},
"email": "ines@acme.test",
"fields": [],
"waiting_for_confirm": true,
"start_date": "2026-10-12",
"last_error": null,
"failures": 0,
"held": null,
"password_to": "ines.martins@home.test"
}
]
}
}Confirm a directory change that waits#
POST/v1/org/directory.confirmWrite
Confirms a change that waits for a person (org_directory_preview waiting_for_confirm): kind create (a new account for someone starting soon; send the password_to shown), reactivate (a rehire's suspended account), suspend or update (held: new_link, the first change since a link, or many, many suspensions at once; only owners and admins confirm held changes). Bizisy then sends it at once; a new account's first password goes to the personal email shown (password_to) as a one-time link, and only if it is still the same when the account is created; otherwise HR reveals it once (org_directory_reveal_password). Owners, admins and HR, in the app only.
- Web app only
- Refused for API keys and connected apps. A person confirms new and reactivated accounts in the app.
- MCP tool
org_directory_confirmon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
provider"google" | "entra"requiredperson_idstringrequiredkind"create" | "reactivate" | "suspend" | "update"requiredpassword_tostring | nullcreate: the password_to shown in
org_directory_preview(required): refused if the personal email changed since.
Returns
person_idstringrequiredconfirmed"create" | "reactivate" | "suspend" | "update"required
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/directory.confirm \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"provider": "google",
"person_id": "p5",
"kind": "create",
"password_to": "ines.martins@home.test"
}'const res = await fetch('https://api.bizisy.com/v1/org/directory.confirm', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"provider": "google",
"person_id": "p5",
"kind": "create",
"password_to": "ines.martins@home.test"
}),
});
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/directory.confirm",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"provider": "google",
"person_id": "p5",
"kind": "create",
"password_to": "ines.martins@home.test",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"person_id": "p5",
"confirmed": "create"
}
}Retry a directory change that failed#
POST/v1/org/directory.retryWrite
Clears a person's directory sync failure so Bizisy tries again at once (after 3 failures a change waits for this). Owners, admins and HR, in the app only.
- Web app only
- Refused for API keys and connected apps. Retrying a failed change happens in the app.
- MCP tool
org_directory_retryon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
provider"google" | "entra"requiredperson_idstringrequired
Returns
person_idstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/directory.retry \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"provider":"google","person_id":"p2"}'const res = await fetch('https://api.bizisy.com/v1/org/directory.retry', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"provider": "google",
"person_id": "p2"
}),
});
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/directory.retry",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"provider": "google",
"person_id": "p2",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"person_id": "p2"
}
}Reveal a new account's first password#
POST/v1/org/directory.reveal_passwordWrite
Shows, once, the first password of a directory account Bizisy created for someone with no personal email: hand it over privately; they choose their own at first sign-in. After this it is gone. Owners, admins and HR, in the app only.
- Web app only
- Refused for API keys and connected apps. A first password is shown only in the app, once.
- MCP tool
org_directory_reveal_passwordon 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
provider"google" | "entra"requiredperson_idstringrequired
Returns
person_idstringrequiredaccountstringrequiredpasswordstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/directory.reveal_password \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"provider":"google","person_id":"p5"}'const res = await fetch('https://api.bizisy.com/v1/org/directory.reveal_password', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"provider": "google",
"person_id": "p5"
}),
});
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/directory.reveal_password",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"provider": "google",
"person_id": "p5",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"person_id": "p5",
"account": "ines@acme.test",
"password": "Xy7#kp2-mWq9rT4!zN3a"
}
}Something missing or wrong on this page? Write to hello@bizisy.com.