Skip to content

API reference

Connected tools

The tools a company connected to Bizisy (task trackers, identity, recruiting, payroll): what is offered, each connection's state and health, its recent operations, the choices it offers (projects, teams, statuses), and syncing now. Connecting, changing and disconnecting happen in the web app.

7 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.

List integrations and their connections#

POST/v1/integrations/connections.listRead

The tools this Bizisy server can connect to (Jira, Linear, Okta, Nmbrs, …) and, for each, this company's connection: status (connecting, connected, error: Bizisy's access stopped working; removed), the account (label), its health (last_ok_at, last_error, failing: an owner or admin should look) and when it last ran. Tools Bizisy does not offer on this server are not listed, unless the company still has a connection to one. Connecting, changing and disconnecting happen in Bizisy (Integrations). Owners, admins and HR.

Who can call it
Manage key owner admin hr
MCP tool
integrations_connections_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • connectorsobject[]required
    13 fields
    • idstringrequired
    • namestringrequired
    • groupstringrequired
    • descriptionstringrequired
    • auth"oauth2" | "api_token" | "basic" | "none"required
    • availablebooleanrequired

      This server offers it (set up for it). A connection of a tool no longer offered can only be disconnected.

    • pagestringrequired

      Where it is set up in Bizisy (app path).

    • fieldsobject[]required

      api_token / basic: what to type to connect (credentials keys).

      6 fields
      • keystringrequired
      • labelstringrequired
      • secretbooleanrequired
      • kind"text" | "url" | "email"required
      • optionalbooleanrequired
      • helpstring | nullrequired
    • runsbooleanrequired

      Bizisy works with it every hour (and on Sync now).

    • stage"beta" | "stable"required

      beta: it works, and Bizisy is still confirming it with real accounts (say so when you suggest it; it can be connected).

    • module"payroll" | "finance" | "analytics" | "pay_equity" | "more_integrations" | "bank_verification"required

      The module it belongs to (Settings → Modules, included): connecting, changing and syncing are refused with module_disabled while it is off; null: always there.

    • pausedbooleanrequired

      Its module is switched off: the connection stays, but nothing runs and no events are handled until the module is on again ("Paused: switch on <module>").

    • connectionobject | nullrequired
      11 fields
      • status"connecting" | "connected" | "error" | "removed"required

        connecting: started, not finished; connected; error: Bizisy’s access stopped working (connect again); removed: the access was given back (company closing).

      • labelstring | nullrequired

        The connected account as the tool names it (a site, a workspace).

      • account_keystring | nullrequired
      • detailsobjectrequired

        What is not secret about the connection (a site address, a user name).

      • settingsobjectrequired
      • healthobjectrequired
        5 fields
        • last_ok_atstring | nullrequired
        • last_errorstring | nullrequired
        • failing_sincestring | nullrequired
        • consecutive_failuresintegerrequired
        • failingbooleanrequired

          True when the credentials stopped working (status error) or after 3 failures in a row: an owner or admin should look (it shows in Home).

      • connected_atstring | nullrequired
      • last_run_atstring | nullrequired
      • next_run_atstring | nullrequired
      • failureobject | nullrequired

        Why the last attempt to connect failed, until one succeeds: session (finished in another browser or by someone else), denied (access not granted), identify (the tool did not say which account), failed.

        2 fields
        • reason"session" | "denied" | "identify" | "failed"required
        • atstringrequired
      • inbound_urlstring | nullrequired

        Where the tool sends its events for this connection (connectors with their own events secret); null otherwise.

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/integrations/connections.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "connectors": [
      {
        "id": "linear",
        "name": "Linear",
        "group": "tasks",
        "description": "Onboarding and offboarding tasks become Linear issues; their status comes back.",
        "auth": "oauth2",
        "available": true,
        "page": "/manage/integrations/linear",
        "fields": [],
        "runs": true,
        "stage": "beta",
        "module": null,
        "paused": false,
        "connection": {
          "status": "connected",
          "label": "Acme",
          "account_key": "org-1",
          "details": {},
          "settings": {
            "team": null
          },
          "health": {
            "last_ok_at": "2026-10-04T10:00:00.000Z",
            "last_error": null,
            "failing_since": null,
            "consecutive_failures": 0,
            "failing": false
          },
          "connected_at": "2026-10-03T09:12:00.000Z",
          "last_run_at": "2026-10-04T10:00:00.000Z",
          "next_run_at": null,
          "failure": null,
          "inbound_url": null
        }
      }
    ]
  }
}

Get an integration and its recent operations#

POST/v1/integrations/connections.getRead

One integration (as in integrations_connections_list) with its last 50 operations, newest first: what Bizisy did (connect, run, inbound event, refresh, disconnect, or the tool's own step), its outcome (ok, failed, skipped) and a detail that never names anyone. Operations are kept 30 days. Owners, admins and HR.

Who can call it
Manage key owner admin hr
MCP tool
integrations_connections_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • connectorstringrequired

    1–50 characters. Pattern ^[a-z][a-z0-9_]*$.

Returns

14 fields
  • idstringrequired
  • namestringrequired
  • groupstringrequired
  • descriptionstringrequired
  • auth"oauth2" | "api_token" | "basic" | "none"required
  • availablebooleanrequired

    This server offers it (set up for it). A connection of a tool no longer offered can only be disconnected.

  • pagestringrequired

    Where it is set up in Bizisy (app path).

  • fieldsobject[]required

    api_token / basic: what to type to connect (credentials keys).

    6 fields
    • keystringrequired
    • labelstringrequired
    • secretbooleanrequired
    • kind"text" | "url" | "email"required
    • optionalbooleanrequired
    • helpstring | nullrequired
  • runsbooleanrequired

    Bizisy works with it every hour (and on Sync now).

  • stage"beta" | "stable"required

    beta: it works, and Bizisy is still confirming it with real accounts (say so when you suggest it; it can be connected).

  • module"payroll" | "finance" | "analytics" | "pay_equity" | "more_integrations" | "bank_verification"required

    The module it belongs to (Settings → Modules, included): connecting, changing and syncing are refused with module_disabled while it is off; null: always there.

  • pausedbooleanrequired

    Its module is switched off: the connection stays, but nothing runs and no events are handled until the module is on again ("Paused: switch on <module>").

  • connectionobject | nullrequired
    11 fields
    • status"connecting" | "connected" | "error" | "removed"required

      connecting: started, not finished; connected; error: Bizisy’s access stopped working (connect again); removed: the access was given back (company closing).

    • labelstring | nullrequired

      The connected account as the tool names it (a site, a workspace).

    • account_keystring | nullrequired
    • detailsobjectrequired

      What is not secret about the connection (a site address, a user name).

    • settingsobjectrequired
    • healthobjectrequired
      5 fields
      • last_ok_atstring | nullrequired
      • last_errorstring | nullrequired
      • failing_sincestring | nullrequired
      • consecutive_failuresintegerrequired
      • failingbooleanrequired

        True when the credentials stopped working (status error) or after 3 failures in a row: an owner or admin should look (it shows in Home).

    • connected_atstring | nullrequired
    • last_run_atstring | nullrequired
    • next_run_atstring | nullrequired
    • failureobject | nullrequired

      Why the last attempt to connect failed, until one succeeds: session (finished in another browser or by someone else), denied (access not granted), identify (the tool did not say which account), failed.

      2 fields
      • reason"session" | "denied" | "identify" | "failed"required
      • atstringrequired
    • inbound_urlstring | nullrequired

      Where the tool sends its events for this connection (connectors with their own events secret); null otherwise.

  • operationsobject[]required
    4 fields
    • atstringrequired
    • opstringrequired
    • outcome"ok" | "failed" | "skipped"required
    • detailstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/integrations/connections.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"connector":"linear"}'
Response
{
  "data": {
    "id": "linear",
    "name": "Linear",
    "group": "tasks",
    "description": "Onboarding and offboarding tasks become Linear issues; their status comes back.",
    "auth": "oauth2",
    "available": true,
    "page": "/manage/integrations/linear",
    "fields": [],
    "runs": true,
    "stage": "beta",
    "module": null,
    "paused": false,
    "connection": {
      "status": "connected",
      "label": "Acme",
      "account_key": "org-1",
      "details": {},
      "settings": {
        "team": null
      },
      "health": {
        "last_ok_at": "2026-10-04T10:00:00.000Z",
        "last_error": null,
        "failing_since": null,
        "consecutive_failures": 0,
        "failing": false
      },
      "connected_at": "2026-10-03T09:12:00.000Z",
      "last_run_at": "2026-10-04T10:00:00.000Z",
      "next_run_at": null,
      "failure": null,
      "inbound_url": null
    },
    "operations": [
      {
        "at": "2026-10-04T10:00:00.000Z",
        "op": "run",
        "outcome": "ok",
        "detail": "Pushed 2 tasks."
      },
      {
        "at": "2026-10-03T09:12:00.000Z",
        "op": "connect",
        "outcome": "ok",
        "detail": "Connected."
      }
    ]
  }
}

List choices from a connected tool#

POST/v1/integrations/connections.lookupRead

Reads choices from a connected tool for Bizisy settings: its projects, issue types, service desks and request types, teams, sections or statuses (the lookups each connector offers; params narrow them, e.g. { "project": "<id>" } for issue types). At most 500 options: id, name, key (e.g. a project key) and a hint. Fails with the tool's refusal in words (never its own text) when it is not connected or refuses. Owners, admins and HR.

Who can call it
Manage key owner admin hr
MCP tool
integrations_connections_lookup on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • connectorstringrequired

    1–50 characters. Pattern ^[a-z][a-z0-9_]*$.

  • lookupstringrequired

    1–40 characters. Pattern ^[a-z][a-z0-9_]*$.

  • paramsobject

Returns

  • optionsobject[]required
    4 fields
    • idstringrequired
    • namestringrequired
    • keystring | nullrequired
    • hintstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/integrations/connections.lookup \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"connector":"jira","lookup":"issue_types","params":{"project":"10000"}}'
Response
{
  "data": {
    "options": [
      {
        "id": "10001",
        "name": "Task",
        "key": null,
        "hint": null
      },
      {
        "id": "10002",
        "name": "Bug",
        "key": null,
        "hint": null
      }
    ]
  }
}

Connect an integration#

POST/v1/integrations/connections.connectWrite

Starts or finishes connecting a tool. OAuth tools (auth oauth2): returns url, the tool's page where someone allowed to grant access approves Bizisy; it expires in 15 minutes and finishes only in the browser of the person who started. Token or password tools (api_token, basic): send credentials with the keys the connector lists in fields; Bizisy checks them with the tool first (not in a dry run), keeps them encrypted and never shows them again. Connecting again replaces the credentials; another account than before starts over (its links are removed). When the tool sends its own events with a secret Bizisy made for this connection, inbound has the address and the secret, shown once. Owners and admins, in the app only.

Web app only
Refused for API keys and connected apps. An owner or admin connects a tool in the app (Integrations): credentials and access grants never pass through a key.
MCP tool
integrations_connections_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

  • connectorstringrequired

    1–50 characters. Pattern ^[a-z][a-z0-9_]*$.

  • credentialsobject

    api_token / basic: the fields the connector lists (fields), e.g. { "token": "…" }.

Returns

  • status"connecting" | "connected"required
  • urlstring | nullrequired

    OAuth: open it to grant access.

  • expires_atstring | nullrequired
  • labelstring | nullrequired
  • inboundobject | nullrequired
    2 fields
    • urlstringrequired
    • secretstringrequired

      Shown once: paste it in the tool’s webhook settings. Bizisy keeps it encrypted.

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/integrations/connections.connect \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"connector":"teamtailor","credentials":{"token":"tt-api-token"}}'
Response
{
  "data": {
    "status": "connecting",
    "url": "https://linear.app/oauth/authorize?response_type=code&client_id=bizisy&state=o1.xyz",
    "expires_at": "2026-10-04T10:15:00.000Z",
    "label": null,
    "inbound": null
  }
}

Change an integration#

POST/v1/integrations/connections.updateWrite

Changes a connection: its settings (the keys its connector defines; send only what changes) and, with roll_inbound_secret, a new secret for the events the tool sends (shown once; the old one stops at once). Owners and admins, in the app only.

Web app only
Refused for API keys and connected apps. A connection's settings and its events secret change in the app only.
MCP tool
integrations_connections_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

  • connectorstringrequired

    1–50 characters. Pattern ^[a-z][a-z0-9_]*$.

  • settingsobject
  • roll_inbound_secrettrue

Returns

  • connectionobjectrequired
    11 fields
    • status"connecting" | "connected" | "error" | "removed"required

      connecting: started, not finished; connected; error: Bizisy’s access stopped working (connect again); removed: the access was given back (company closing).

    • labelstring | nullrequired

      The connected account as the tool names it (a site, a workspace).

    • account_keystring | nullrequired
    • detailsobjectrequired

      What is not secret about the connection (a site address, a user name).

    • settingsobjectrequired
    • healthobjectrequired
      5 fields
      • last_ok_atstring | nullrequired
      • last_errorstring | nullrequired
      • failing_sincestring | nullrequired
      • consecutive_failuresintegerrequired
      • failingbooleanrequired

        True when the credentials stopped working (status error) or after 3 failures in a row: an owner or admin should look (it shows in Home).

    • connected_atstring | nullrequired
    • last_run_atstring | nullrequired
    • next_run_atstring | nullrequired
    • failureobject | nullrequired

      Why the last attempt to connect failed, until one succeeds: session (finished in another browser or by someone else), denied (access not granted), identify (the tool did not say which account), failed.

      2 fields
      • reason"session" | "denied" | "identify" | "failed"required
      • atstringrequired
    • inbound_urlstring | nullrequired

      Where the tool sends its events for this connection (connectors with their own events secret); null otherwise.

  • inboundobject | nullrequired
    2 fields
    • urlstringrequired
    • secretstringrequired

      Shown once: paste it in the tool’s webhook settings. Bizisy keeps it encrypted.

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/integrations/connections.update \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"connector":"teamtailor","roll_inbound_secret":true}'
Response
{
  "data": {
    "connection": {
      "status": "connected",
      "label": "Acme",
      "account_key": "org-1",
      "details": {},
      "settings": {
        "team": "ENG"
      },
      "health": {
        "last_ok_at": "2026-10-04T10:00:00.000Z",
        "last_error": null,
        "failing_since": null,
        "consecutive_failures": 0,
        "failing": false
      },
      "connected_at": "2026-10-03T09:12:00.000Z",
      "last_run_at": "2026-10-04T10:00:00.000Z",
      "next_run_at": null,
      "failure": null,
      "inbound_url": null
    },
    "inbound": null
  }
}

Sync an integration now#

POST/v1/integrations/connections.runWrite

Asks a connected tool to do its work now instead of at the next hourly run (at most 6 times an hour); the answer comes when it is done or after 10 seconds (then it carries on). See integrations_connections_get for the outcome. A dry run starts nothing. Owners and admins.

Who can call it
Manage key owner admin
MCP tool
integrations_connections_run on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • connectorstringrequired

    1–50 characters. Pattern ^[a-z][a-z0-9_]*$.

Returns

  • startedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/integrations/connections.run \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"connector":"linear"}'
Response
{
  "data": {
    "started": true
  }
}

Disconnect an integration#

POST/v1/integrations/connections.disconnectDestructive

Disconnects a tool: Bizisy forgets its credentials, settings and the links between Bizisy records and the tool's, and gives its access back to the tool where it can. Nothing is deleted in the tool itself. The operation log stays for 30 days. Owners and admins, in the app only.

Web app only
Refused for API keys and connected apps. Disconnecting happens in the app.
MCP tool
integrations_connections_disconnect on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • connectorstringrequired

    1–50 characters. Pattern ^[a-z][a-z0-9_]*$.

Returns

  • connectorstringrequired
  • disconnectedtruerequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/integrations/connections.disconnect \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"connector":"linear"}'
Response
{
  "data": {
    "connector": "linear",
    "disconnected": true
  }
}

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

Developer docs