Skip to content

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

Input

No input: send {}.

Returns

  • providersobject[]required
    5 fields
    • provider"google" | "entra"required
    • namestringrequired
    • availablebooleanrequired

      The server can connect this provider (its OAuth app is set up); false: not available yet.

    • connectionobject | nullrequired
      9 fields
      • status"pending" | "connected" | "error"required
      • labelstring | nullrequired
      • domainsstring[]required
      • connected_atstring | nullrequired
      • errorstring | nullrequired
      • setup_completebooleanrequired

        False 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 | nullrequired

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

          One of: session, not_admin, taken, denied, scopes, refused, propagating, failed.

        • atstringrequired
      • foundobject | nullrequired

        Accounts 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
        • countintegerrequired
        • morebooleanrequired
      • settingsobjectrequired
        5 fields
        • create"confirm" | "auto"required
        • days_beforeintegerrequired
        • suspendbooleanrequired
        • org_unitstring | nullrequired

          Google: the organizational unit path new accounts go to (null: the root). Always null for Entra.

        • groupsobject[]required
          4 fields
          • unit_idstringrequired
          • unit_namestring | nullrequired
          • group_idstringrequired
          • group_namestringrequired
    • countsobjectrequired
      6 fields
      • linkedintegerrequired
      • excludedintegerrequired
      • adminintegerrequired
      • pendingintegerrequired

        Changes the next run sends (creations waiting for HR not included).

      • waiting_for_confirmintegerrequired
      • failedintegerrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/directory.status \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "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_connect 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

  • provider"google" | "entra"required

Returns

  • urlstringrequired
  • expires_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

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

Input

  • provider"google" | "entra"required

Returns

  • provider"google" | "entra"required
  • disconnectedtruerequired
  • next_stepstring | nullrequired

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

Input

  • provider"google" | "entra"required
  • create"confirm" | "auto"
  • days_beforeinteger

    From 0 to 14.

  • suspendboolean
  • groupsobject[]

    Up to 100 items.

    3 fields
    • unit_idstringrequired
    • group_idstringrequired

      1–200 characters.

    • group_namestringrequired

      1–200 characters.

  • org_unitstring | null

    Pattern ^\/[^\n\r]{0,499}$.

  • setup_completetrue

Returns

  • provider"google" | "entra"required
  • settingsobjectrequired
    5 fields
    • create"confirm" | "auto"required
    • days_beforeintegerrequired
    • suspendbooleanrequired
    • org_unitstring | nullrequired
    • groupsobject[]required
      3 fields
      • unit_idstringrequired
      • group_idstringrequired
      • group_namestringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
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"
    }
  ]
}'
Response
{
  "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_groups on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • provider"google" | "entra"required
  • qstring

    Up to 100 characters.

Returns

  • groupsobject[]required
    3 fields
    • idstringrequired
    • namestringrequired
    • emailstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
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"}'
Response
{
  "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_users on HR Assistant
Method
POST with a JSON body only (an input field carries a secret)

Input

  • provider"google" | "entra"required
  • qstring

    Up to 100 characters.

  • page_tokenstring

    Up to 500 characters.

Returns

  • usersobject[]required
    8 fields
    • account_idstringrequired
    • emailstringrequired
    • namestringrequired
    • titlestring | nullrequired
    • departmentstring | nullrequired
    • suspendedbooleanrequired
    • adminbooleanrequired
    • matchobject | nullrequired

      The person in Bizisy with this work email; linked: already linked to this account.

      3 fields
      • person_idstringrequired
      • namestringrequired
      • linkedbooleanrequired
  • next_page_tokenstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

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

  • provider"google" | "entra"required
  • account_idsstring[]required

    1–200 characters. 1–200 items.

  • send"now" | "none"

    Default "now".

  • role"member" | "viewer" | "hr" | "admin"

Returns

  • linkedintegerrequired
  • invitedintegerrequired
  • skippedobject[]required
    2 fields
    • account_idstringrequired
    • reasonstringrequired
  • departments_without_teamstring[]required

    Directory 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
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"
}'
Response
{
  "data": {
    "linked": 1,
    "invited": 1,
    "skipped": [],
    "departments_without_team": [
      "Legal"
    ]
  }
}

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_link on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • provider"google" | "entra"required
  • person_idstringrequired
  • account_idstring | nullrequired

    1–200 characters.

  • confirm_mismatchboolean

    Owners and admins: link an account whose email is not the person's work email (checked by you to be theirs).

Returns

  • person_idstringrequired
  • account_emailstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

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

Input

  • provider"google" | "entra"required
  • person_idstringrequired
  • excludedbooleanrequired

Returns

  • person_idstringrequired
  • excludedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
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}'
Response
{
  "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_preview on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • provider"google" | "entra"required

Returns

  • itemsobject[]required
    10 fields
    • kind"create" | "update" | "suspend" | "reactivate"required
    • personobjectrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • emailstringrequired
    • fieldsstring[]required
    • waiting_for_confirmbooleanrequired
    • start_datestring | nullrequired
    • last_errorstring | nullrequired
    • failuresintegerrequired
    • held"new_link" | "many"required

      suspend 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 | nullrequired

      create: 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
curl https://api.bizisy.com/v1/org/directory.preview \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"google"}'
Response
{
  "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_confirm on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • provider"google" | "entra"required
  • person_idstringrequired
  • kind"create" | "reactivate" | "suspend" | "update"required
  • password_tostring | null

    create: the password_to shown in org_directory_preview (required): refused if the personal email changed since.

Returns

  • person_idstringrequired
  • confirmed"create" | "reactivate" | "suspend" | "update"required

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

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

Input

  • provider"google" | "entra"required
  • person_idstringrequired

Returns

  • person_idstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

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

  • provider"google" | "entra"required
  • person_idstringrequired

Returns

  • person_idstringrequired
  • accountstringrequired
  • passwordstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

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

Developer docs