Skip to content

API reference

Payroll tools

Send a locked pay period to Staffology, Xero Payroll (UK) or Silae: where each legal entity goes, the preview of what goes per person, the send (in the app, bound to the preview, with consent for pay and private data) and the log of what was sent.

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

List payroll tools Bizisy sends to#

POST/v1/payroll/push.targetsRead

The payroll tools this server can send locked pay periods to (Staffology, Xero Payroll, Silae), each with its connection state, whether its connection may receive pay and private data (consent), where each legal entity goes and its options, the answers it asks for new employees, and the last send per legal entity. Owners, admins, HR and roles with Payroll. Part of the Payroll 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
payroll_push_targets on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • targetsobject[]required
    15 fields
    • connectorstringrequired
    • namestringrequired
    • countriesstring[]required
    • status"connecting" | "connected" | "error" | "removed"required
    • labelstring | nullrequired
    • pagestring | nullrequired
    • consentobjectrequired
      3 fields
      • allowedbooleanrequired
      • missing"pay" | "private"[]required
      • granteeobject | nullrequired
        3 fields
        • kind"connection"required
        • idstringrequired
        • namestringrequired
    • answers"title" | "gender" | "marital_status" | "starter_declaration" | "ni_category"[]required
    • code_keystringrequired
    • employeesbooleanrequired
    • leaversbooleanrequired
    • units"amount" | "hours" | "days"[]required
    • accountobjectrequired
      2 fields
      • labelstringrequired
      • lookupstringrequired
    • optionsobject[]required
      4 fields
      • keystringrequired
      • labelstringrequired
      • lookupstringrequired
      • requiredbooleanrequired
    • entitiesobject[]required
      4 fields
      • legal_entity_idstringrequired
      • accountobjectrequired
        2 fields
        • idstringrequired
        • namestringrequired
      • optionsobjectrequired
      • last_pushobject | nullrequired
        8 fields
        • idstringrequired
        • period_idstringrequired
        • connectorstringrequired
        • status"queued" | "sending" | "sent" | "partial" | "failed"required
        • requested_atstringrequired
        • finished_atstring | nullrequired
        • countsobjectrequired
          4 fields
          • peopleintegerrequired
          • sentintegerrequired
          • failedintegerrequired
          • skippedintegerrequired
        • resultsobject[]required
          4 fields
          • person_idstring | nullrequired
          • op"employee" | "leaver" | "pay" | "push"required
          • outcome"ok" | "failed" | "skipped"required
          • messagestringrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/push.targets \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "targets": [
      {
        "connector": "staffology",
        "name": "Staffology",
        "countries": [
          "GB"
        ],
        "status": "connected",
        "label": "Acme UK Ltd",
        "page": "/manage/integrations/staffology",
        "consent": {
          "allowed": true,
          "missing": [],
          "grantee": {
            "kind": "connection",
            "id": "staffology:3f2a",
            "name": "Staffology (Acme UK Ltd)"
          }
        },
        "answers": [
          "gender",
          "marital_status",
          "starter_declaration"
        ],
        "code_key": "staffology",
        "employees": true,
        "leavers": true,
        "units": [
          "amount"
        ],
        "account": {
          "label": "Staffology employer",
          "lookup": "employers"
        },
        "options": [],
        "entities": [
          {
            "legal_entity_id": "e1",
            "account": {
              "id": "11111111-2222-3333-4444-555555555555",
              "name": "Acme UK Ltd"
            },
            "options": {},
            "last_push": {
              "id": "push1",
              "period_id": "e1:2026-03-01",
              "connector": "staffology",
              "status": "partial",
              "requested_at": "2026-04-02T09:00:00.000Z",
              "finished_at": "2026-04-02T09:00:05.000Z",
              "counts": {
                "people": 2,
                "sent": 2,
                "failed": 1,
                "skipped": 0
              },
              "results": []
            }
          }
        ]
      }
    ]
  }
}

Choose where a legal entity goes in a payroll tool#

POST/v1/payroll/push.mapWrite

Sets where one legal entity's pay periods go in a connected payroll tool: account_id (the Staffology employer; for tools with one account per connection, the connection's account) with account_name, and the tool's options (Xero: payroll_calendar). account_id null stops sending that entity. Ids come from integrations_connections_lookup. Owners, admins, HR and roles with Payroll at Edit. Part of the Payroll 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
payroll_push_map on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • legal_entity_idstringrequired
  • connector"staffology" | "xero_payroll" | "silae"required

    The payroll tool: see payroll_push_targets.

  • account_idstring | nullrequired

    1–200 characters.

  • account_namestring

    Up to 200 characters. Default "".

  • optionsobject

    Default {}.

Returns

  • legal_entity_idstringrequired
  • connectorstringrequired
  • accountobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • optionsobjectrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/push.map \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "legal_entity_id": "e1",
  "connector": "xero_payroll",
  "account_id": "tenant-1",
  "account_name": "Acme UK",
  "options": {
    "payroll_calendar": "22222222-3333-4444-5555-666666666666"
  }
}'
Response
{
  "data": {
    "legal_entity_id": "e1",
    "connector": "xero_payroll",
    "account": {
      "id": "11111111-2222-3333-4444-555555555555",
      "name": "Acme UK Ltd"
    },
    "options": {}
  }
}

Preview sending a pay period to a payroll tool#

POST/v1/payroll/push.previewRead

What sending a locked pay period to a payroll tool would do, per person: the employee record (create, update with the fields that changed, or match by employee number), the leaver, and the variable pay items with the tool's pay codes; problems say what will not go and why. Also: whether the connection may receive pay and private data (consent), the answers the tool needs for new people (answers_needed), plan_hash (pass it to payroll_push_send), ready and blocked (why it cannot be sent yet). Nothing is sent. Owners, admins, HR and roles with Payroll at Edit that cover the whole period; API keys and AI apps see values only with a consent. Part of the Payroll 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
Keys and apps
Pay values only with a consent (Payroll → Settings → Machine access); otherwise null.
MCP tool
payroll_push_preview on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • period_idstringrequired

    A period id from payroll_overview or payroll_periods_get: "<legal entity id>:<start date>".

    12–120 characters.

  • connector"staffology" | "xero_payroll" | "silae"required

    The payroll tool: see payroll_push_targets.

Returns

11 fields
  • period_idstringrequired
  • connectorstringrequired
  • accountobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • rowsobject[]required
    9 fields
    • person_idstringrequired
    • namestringrequired
    • employee_numberstring | nullrequired
    • employee"create" | "update" | "match"required

      create: new in the tool; update: payroll data changed; match: found by employee number, else created.

    • fieldsstring (enum)[]required

      One of: given_name, family_name, birthday, address, tax_id, social_security_number, iban, employee_number, start_date, title, weekly_hours, fte, contract_type, pay.

    • leaverobject | nullrequired
      2 fields
      • last_daystringrequired
      • reasonstring | nullrequired
    • itemsobject[]required
      7 fields
      • item_idstringrequired
      • codestringrequired
      • namestringrequired
      • kind"earning" | "deduction"required
      • unit"amount" | "hours" | "days"required
      • valuenumber | nullrequired
      • currencystring | nullrequired
    • problemsstring[]required
    • needs_answersbooleanrequired
  • skipped_itemsintegerrequired
  • consentobjectrequired
    3 fields
    • allowedbooleanrequired
    • missing"pay" | "private"[]required
    • granteeobject | nullrequired
      3 fields
      • kind"connection"required
      • idstringrequired
      • namestringrequired
  • answers_needed"title" | "gender" | "marital_status" | "starter_declaration" | "ni_category"[]required
  • plan_hashstring | nullrequired

    Pass it to payroll_push_send; null for callers who do not see pay values.

  • readybooleanrequired
  • blockedstring | nullrequired
  • last_pushobject | nullrequired
    8 fields
    • idstringrequired
    • period_idstringrequired
    • connectorstringrequired
    • status"queued" | "sending" | "sent" | "partial" | "failed"required
    • requested_atstringrequired
    • finished_atstring | nullrequired
    • countsobjectrequired
      4 fields
      • peopleintegerrequired
      • sentintegerrequired
      • failedintegerrequired
      • skippedintegerrequired
    • resultsobject[]required
      4 fields
      • person_idstring | nullrequired
      • op"employee" | "leaver" | "pay" | "push"required
      • outcome"ok" | "failed" | "skipped"required
      • messagestringrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/push.preview \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"period_id":"e1:2026-03-01","connector":"staffology"}'
Response
{
  "data": {
    "period_id": "e1:2026-03-01",
    "connector": "staffology",
    "account": {
      "id": "11111111-2222-3333-4444-555555555555",
      "name": "Acme UK Ltd"
    },
    "rows": [
      {
        "person_id": "p2",
        "name": "Bruno Costa",
        "employee_number": "1002",
        "employee": "create",
        "fields": [
          "given_name",
          "family_name",
          "birthday",
          "address",
          "employee_number",
          "start_date",
          "pay"
        ],
        "leaver": null,
        "items": [
          {
            "item_id": "i1",
            "code": "BONUS",
            "name": "Bonus",
            "kind": "earning",
            "unit": "amount",
            "value": 500,
            "currency": "GBP"
          }
        ],
        "problems": [],
        "needs_answers": true
      },
      {
        "person_id": "p1",
        "name": "Ana Ferreira",
        "employee_number": "1001",
        "employee": null,
        "fields": [],
        "leaver": {
          "last_day": "2026-03-20",
          "reason": "resignation"
        },
        "items": [],
        "problems": [
          "The pay item \"Overtime\" has no Staffology pay code in Pay items."
        ],
        "needs_answers": false
      }
    ],
    "skipped_items": 1,
    "consent": {
      "allowed": true,
      "missing": [],
      "grantee": {
        "kind": "connection",
        "id": "staffology:3f2a",
        "name": "Staffology (Acme UK Ltd)"
      }
    },
    "answers_needed": [
      "gender",
      "marital_status",
      "starter_declaration"
    ],
    "plan_hash": "3b1f0c9a2d4e5f60718293a4b5c6d7e8",
    "ready": true,
    "blocked": null,
    "last_push": null
  }
}

Send a pay period to a payroll tool#

POST/v1/payroll/push.sendWrite

Sends a locked pay period to a connected payroll tool, exactly as payroll_push_preview showed it: pass its plan_hash (a different plan is refused: preview again). New employees need the tool's answers (answers_needed; e.g. Staffology's gender, marital status and HMRC starter declaration), one entry per person; Bizisy keeps them only until they are sent. Needs the connection's consent for pay and private data. Queues the send and starts it; follow it with payroll_push_log. One send per period and tool at a time; at most 50 per period. In the app only. Owners, admins, HR and roles with Payroll at Edit that cover the whole period. Part of the Payroll 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. Sending a pay period to a payroll tool happens in the app only.
MCP tool
payroll_push_send 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

  • period_idstringrequired

    A period id from payroll_overview or payroll_periods_get: "<legal entity id>:<start date>".

    12–120 characters.

  • connector"staffology" | "xero_payroll" | "silae"required

    The payroll tool: see payroll_push_targets.

  • plan_hashstringrequired

    8–64 characters.

  • answersobject[]

    Up to 2000 items.

    6 fields
    • person_idstringrequired
    • titlestring

      Up to 40 characters.

    • genderstring

      Up to 40 characters.

    • marital_statusstring

      Up to 40 characters.

    • starter_declarationstring

      Up to 40 characters.

    • ni_categorystring

      Up to 40 characters.

Returns

8 fields
  • idstringrequired
  • period_idstringrequired
  • connectorstringrequired
  • status"queued" | "sending" | "sent" | "partial" | "failed"required
  • requested_atstringrequired
  • finished_atstring | nullrequired
  • countsobjectrequired
    4 fields
    • peopleintegerrequired
    • sentintegerrequired
    • failedintegerrequired
    • skippedintegerrequired
  • resultsobject[]required
    4 fields
    • person_idstring | nullrequired
    • op"employee" | "leaver" | "pay" | "push"required
    • outcome"ok" | "failed" | "skipped"required
    • messagestringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/push.send \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "period_id": "e1:2026-03-01",
  "connector": "staffology",
  "plan_hash": "3b1f0c9a2d4e5f60718293a4b5c6d7e8",
  "answers": [
    {
      "person_id": "p2",
      "gender": "female",
      "marital_status": "single",
      "starter_declaration": "A"
    }
  ]
}'
Response
{
  "data": {
    "id": "push1",
    "period_id": "e1:2026-03-01",
    "connector": "staffology",
    "status": "queued",
    "requested_at": "2026-04-02T09:00:00.000Z",
    "finished_at": null,
    "counts": {
      "people": 2,
      "sent": 0,
      "failed": 0,
      "skipped": 0
    },
    "results": []
  }
}

Read what was sent to payroll tools#

POST/v1/payroll/push.logRead

The sends of a pay period to payroll tools, newest first: tool, status (queued, sending, sent, partial, failed), when, counts and per-person results (employee, leaver, pay or the whole send; ok, failed or skipped; a sentence of Bizisy's). Owners, admins, HR and roles with Payroll that cover the whole period. Part of the Payroll 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
payroll_push_log on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • period_idstringrequired

    A period id from payroll_overview or payroll_periods_get: "<legal entity id>:<start date>".

    12–120 characters.

Returns

  • pushesobject[]required
    8 fields
    • idstringrequired
    • period_idstringrequired
    • connectorstringrequired
    • status"queued" | "sending" | "sent" | "partial" | "failed"required
    • requested_atstringrequired
    • finished_atstring | nullrequired
    • countsobjectrequired
      4 fields
      • peopleintegerrequired
      • sentintegerrequired
      • failedintegerrequired
      • skippedintegerrequired
    • resultsobject[]required
      4 fields
      • person_idstring | nullrequired
      • op"employee" | "leaver" | "pay" | "push"required
      • outcome"ok" | "failed" | "skipped"required
      • messagestringrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/push.log \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"period_id":"e1:2026-03-01"}'
Response
{
  "data": {
    "pushes": [
      {
        "id": "push1",
        "period_id": "e1:2026-03-01",
        "connector": "staffology",
        "status": "partial",
        "requested_at": "2026-04-02T09:00:00.000Z",
        "finished_at": "2026-04-02T09:00:05.000Z",
        "counts": {
          "people": 2,
          "sent": 2,
          "failed": 1,
          "skipped": 0
        },
        "results": [
          {
            "person_id": "p2",
            "op": "employee",
            "outcome": "ok",
            "message": "In Staffology."
          },
          {
            "person_id": "p1",
            "op": "leaver",
            "outcome": "ok",
            "message": "Recorded as a leaver in Staffology."
          },
          {
            "person_id": "p2",
            "op": "pay",
            "outcome": "failed",
            "message": "Staffology took no pay items: open the monthly pay run for this period in Staffology with these people on it, check the pay codes, then send again."
          }
        ]
      }
    ]
  }
}

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

Developer docs