Skip to content

API reference

Spend tools (Pleo, Moss, Payhawk, Spendesk)

What Bizisy does in each spend tool its API allows (invites, teams or cost centres, approvers from team leads, blocking a leaver's cards), the plan before syncing starts and what HR does in the tool itself. Connecting, starting, confirming and excluding happen in the web app.

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

Spend tools status#

POST/v1/org/spend.statusRead

Pleo, Moss, Payhawk and Spendesk (spec integration-platform-spend): for each, what its API lets Bizisy do (capabilities: invite people, teams or cost centres, approvers, block leavers' cards), whether it is connected, whether syncing has started (started: false means Bizisy only reads it and shows the plan until an owner or admin clicks Start syncing), the settings (team mapping with team names), when it was last read, and counts (people matched by work email, excluded, administrators never touched, people in the tool who are not in Bizisy, changes the next run sends, changes waiting for a person, failed changes, checks: things to do in the tool itself). Connecting and settings are integrations_connections_*. Owners, admins and HR; never custom roles. Part of the Finance module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules); this read of stored data keeps working while it is off.

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

Input

No input: send {}.

Returns

  • toolsobject[]required
    10 fields
    • connector"pleo" | "moss" | "payhawk" | "spendesk"required
    • namestringrequired
    • availablebooleanrequired

      This server offers it (Pleo needs Bizisy's partner app).

    • capabilitiesobjectrequired
      6 fields
      • invitebooleanrequired
      • groups"teams" | "cost_centres" | "read"required
      • approvers"team_manager" | "owner" | "read"required
      • offboard"block_cards"required
      • single_teambooleanrequired
      • admins_knownbooleanrequired
    • connectionobject | nullrequired
      5 fields
      • statusstringrequired
      • labelstring | nullrequired
      • connected_onstring | nullrequired
      • failingbooleanrequired
      • last_errorstring | nullrequired
    • startedbooleanrequired
    • read_atstring | nullrequired
    • truncatedbooleanrequired
    • settingsobjectrequired
      6 fields
      • create"off" | "confirm" | "auto"required

        Payhawk: confirm (HR confirms each invite), auto (invited days_before the start), off (a reminder only).

      • days_beforeintegerrequired

        From 0 to 14.

      • create_for"everyone" | "mapped"required

        everyone starting, or only people whose team maps to a group of the tool.

      • teamsobject[]required
        4 fields
        • unit_idstringrequired
        • unit_namestring | nullrequired
        • group_idstring | nullrequired
        • group_namestring | nullrequired
      • approversbooleanrequired

        The mapped team's lead is its approver in the tool (Payhawk team manager, Spendesk cost-centre owner).

      • offboardbooleanrequired

        Payhawk: block a leaver's active cards the day after the last day.

    • countsobjectrequired
      9 fields
      • matchedintegerrequired
      • excludedintegerrequired
      • adminsintegerrequired
      • unmatched_in_toolintegerrequired
      • changesintegerrequired
      • waitingintegerrequired
      • failedintegerrequired
      • checksintegerrequired
      • groupsintegerrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/spend.status \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "tools": [
      {
        "connector": "payhawk",
        "name": "Payhawk",
        "available": true,
        "capabilities": {
          "invite": true,
          "groups": "teams",
          "approvers": "team_manager",
          "offboard": "block_cards",
          "single_team": false,
          "admins_known": true
        },
        "connection": {
          "status": "connected",
          "label": "Acme Payhawk",
          "connected_on": "2026-10-01",
          "failing": false,
          "last_error": null
        },
        "started": true,
        "read_at": "2026-10-04T10:00:00.000Z",
        "truncated": false,
        "settings": {
          "create": "confirm",
          "days_before": 3,
          "create_for": "everyone",
          "approvers": true,
          "offboard": true,
          "teams": [
            {
              "unit_id": "u2",
              "unit_name": "Engineering",
              "group_id": "t1",
              "group_name": "Engineering"
            }
          ]
        },
        "counts": {
          "matched": 12,
          "excluded": 1,
          "admins": 2,
          "unmatched_in_tool": 1,
          "changes": 2,
          "waiting": 1,
          "failed": 0,
          "checks": 1,
          "groups": 3
        }
      },
      {
        "connector": "pleo",
        "name": "Pleo",
        "available": false,
        "capabilities": {
          "invite": false,
          "groups": "teams",
          "approvers": null,
          "offboard": null,
          "single_team": true,
          "admins_known": false
        },
        "connection": null,
        "started": false,
        "read_at": null,
        "truncated": false,
        "settings": {
          "create": "confirm",
          "days_before": 3,
          "create_for": "everyone",
          "approvers": true,
          "offboard": true,
          "teams": []
        },
        "counts": {
          "matched": 0,
          "excluded": 0,
          "admins": 0,
          "unmatched_in_tool": 0,
          "changes": 0,
          "waiting": 0,
          "failed": 0,
          "checks": 0,
          "groups": 0
        }
      }
    ]
  }
}

Preview a spend tool sync#

POST/v1/org/spend.previewRead

What the next run does in a connected spend tool (a dry run: nothing is sent), from Bizisy today and the tool as last read: changes (offboard: block a leaver's cards; invite; group_create / group_rename; team: move between the groups Bizisy manages; approver: the team lead as approver), each waiting_for_confirm or not, with its last error; and checks: what HR does in the tool itself because its API can't (deactivate a leaver, invite a starter, differences). Before Start syncing, this is the plan an owner or admin reviews. Names are public; no private or pay data. Owners, admins and HR; never custom roles. Part of the Finance module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).

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

Input

  • connector"pleo" | "moss" | "payhawk" | "spendesk"required

Returns

  • startedbooleanrequired
  • read_atstring | nullrequired
  • itemsobject[]required
    11 fields
    • kind"offboard" | "invite" | "group_create" | "group_rename" | "team" | "approver"required

      offboard: block the leaver's active cards (Payhawk); invite: a new account; group_create / group_rename: a team or cost centre; team: move the person between the groups Bizisy manages; approver: the team's lead becomes its approver.

    • personobject | nullrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • teamobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • groupobject | nullrequired

      The tool's group it goes to (null: still to create).

      2 fields
      • idstringrequired
      • namestringrequired
    • from_groupsobject[]required
      2 fields
      • idstringrequired
      • namestringrequired
    • emailstring | nullrequired

      invite: the work email the tool sends its invitation to.

    • waiting_for_confirmbooleanrequired
    • held"new_link" | "many"required

      Why a card block waits for an owner or admin: new_link (the first change to an account Bizisy did not create: is it theirs?), many (many at once).

    • start_datestring | nullrequired

      invite: the first day; offboard: the last day.

    • last_errorstring | nullrequired
    • failuresintegerrequired
  • checksobject[]required
    4 fields
    • kindstring (enum)required

      To do in the tool itself (its API can't): leaver_active (left, still active there: deactivate or remove them), invite_manually (starts soon, no account: invite them there), manager_differs / team_differs (the tool says otherwise than Bizisy), approver_missing (the team lead has no account there), approver_differs (Spendesk: the cost centre has an owner the company chose, so Bizisy leaves it), other_team (Pleo: in a team Bizisy does not manage).

      One of: leaver_active, invite_manually, manager_differs, team_differs, approver_missing, approver_differs, other_team.

    • personobject | nullrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • titlestring | nullrequired
      • photo_urlstring | nullrequired
    • teamobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • datestring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/spend.preview \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"connector":"payhawk"}'
Response
{
  "data": {
    "started": true,
    "read_at": "2026-10-04T10:00:00.000Z",
    "items": [
      {
        "kind": "invite",
        "person": {
          "id": "p2",
          "name": "Rui Costa",
          "title": "CTO",
          "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
        },
        "team": {
          "id": "u2",
          "name": "Engineering"
        },
        "group": null,
        "from_groups": [],
        "email": "ines@acme.test",
        "waiting_for_confirm": true,
        "held": null,
        "start_date": "2026-10-12",
        "last_error": null,
        "failures": 0
      },
      {
        "kind": "team",
        "person": {
          "id": "p2",
          "name": "Rui Costa",
          "title": "CTO",
          "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
        },
        "team": {
          "id": "u2",
          "name": "Engineering"
        },
        "group": {
          "id": "t1",
          "name": "Engineering"
        },
        "from_groups": [
          {
            "id": "t2",
            "name": "Sales"
          }
        ],
        "email": null,
        "waiting_for_confirm": false,
        "held": null,
        "start_date": null,
        "last_error": null,
        "failures": 0
      }
    ],
    "checks": [
      {
        "kind": "leaver_active",
        "person": {
          "id": "p2",
          "name": "Rui Costa",
          "title": "CTO",
          "photo_url": "https://acme.bizisy.com/api/photos/people/p2?v=01k0000000000000000000000b"
        },
        "team": null,
        "date": "2026-09-30"
      }
    ]
  }
}

Teams or cost centres of a spend tool#

POST/v1/org/spend.groupsRead

The teams (Pleo, Moss, Payhawk) or cost centres (Spendesk) of a connected spend tool as Bizisy last read them, to map Bizisy teams onto (settings teams in integrations_connections_update), with whether Bizisy created each one. Read again with integrations_connections_run. Owners, admins and HR; never custom roles. Part of the Finance module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).

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

Input

  • connector"pleo" | "moss" | "payhawk" | "spendesk"required

Returns

  • read_atstring | nullrequired
  • groupsobject[]required
    4 fields
    • idstringrequired
    • namestringrequired
    • archivedbooleanrequired
    • created_by_bizisybooleanrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/org/spend.groups \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"connector":"spendesk"}'
Response
{
  "data": {
    "read_at": "2026-10-04T10:00:00.000Z",
    "groups": [
      {
        "id": "cc1",
        "name": "Engineering",
        "archived": false,
        "created_by_bizisy": true
      }
    ]
  }
}

Start syncing a spend tool#

POST/v1/org/spend.startWrite

After reviewing the plan (org_spend_preview), starts sending it: from now on each run (hourly, and right now) makes the changes the plan lists, except those waiting for a person. Until then Bizisy only reads the tool. Refused before the tool was read once. Owners and admins, in the app only. Part of the Finance module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).

Web app only
Refused for API keys and connected apps. An owner or admin starts syncing a spend tool in the app, after reviewing the plan.
MCP tool
org_spend_start on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • connector"pleo" | "moss" | "payhawk" | "spendesk"required

Returns

  • connector"pleo" | "moss" | "payhawk" | "spendesk"required
  • started_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/spend.start \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"connector":"payhawk"}'
Response
{
  "data": {
    "connector": "payhawk",
    "started_at": "2026-10-04T10:00:00.000Z"
  }
}

Confirm a spend tool change that waits#

POST/v1/org/spend.confirmWrite

Confirms a change that waits for a person (org_spend_preview waiting_for_confirm): kind invite (Payhawk invites someone starting soon: the tool emails its invitation to their work email), offboard (block a leaver's active cards, held as the first change to an account Bizisy did not create, or as many at once) or approver (the team lead becomes the approver of their team or cost centre: spending authority, so it waits until someone checks the tool account matched by work email is theirs). Held changes and approvers: owners and admins only. Bizisy sends it at once. Nobody confirms a change about themselves. Owners, admins and HR, in the app only. Part of the Finance module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).

Web app only
Refused for API keys and connected apps. A person confirms invites and card blocks in the app.
MCP tool
org_spend_confirm on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • connector"pleo" | "moss" | "payhawk" | "spendesk"required
  • person_idstringrequired

    1–64 characters.

  • kind"invite" | "offboard" | "approver"required

Returns

  • person_idstringrequired
  • confirmed"invite" | "offboard" | "approver"required

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/spend.confirm \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"connector":"payhawk","person_id":"p9","kind":"offboard"}'
Response
{
  "data": {
    "person_id": "p5",
    "confirmed": "invite"
  }
}

Keep a person out of a spend tool sync#

POST/v1/org/spend.excludeWrite

Excludes a person from a spend tool's sync (excluded true: Bizisy never invites, moves, makes approver or blocks the cards of them there, and lists no checks about them) or includes them again. Nobody keeps themselves out; keeping out someone who has left is for owners and admins. Owners, admins and HR, in the app only. Part of the Finance module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).

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

Input

  • connector"pleo" | "moss" | "payhawk" | "spendesk"required
  • person_idstringrequired

    1–64 characters.

  • excludedbooleanrequired

Returns

  • person_idstringrequired
  • excludedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/spend.exclude \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"connector":"moss","person_id":"p1","excluded":true}'
Response
{
  "data": {
    "person_id": "p1",
    "excluded": true
  }
}

Retry a spend tool change that failed#

POST/v1/org/spend.retryWrite

Clears a failure so Bizisy tries again at once (after 3 failures a change waits for this): a person's (person_id) or a team's group change (team_id: creating, renaming or the approver of its team or cost centre). Owners, admins and HR, in the app only. Part of the Finance module (included): companies with it switched off get module_disabled (an owner or admin switches it on in Manage → Settings → Modules).

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

Input

  • connector"pleo" | "moss" | "payhawk" | "spendesk"required
  • person_idstring

    1–64 characters.

  • team_idstring

    1–64 characters.

Returns

  • retriedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/org/spend.retry \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"connector":"payhawk","person_id":"p2"}'
Response
{
  "data": {
    "retried": true
  }
}

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

Developer docs