Skip to content

API reference

Payroll

Pay periods per legal entity and their change sets (hires, leavers, changes, pay, variable pay), locking, exports for the payroll provider (Excel, CSV, JSON, DATEV LODAS, BrightPay), payslips, net pay and the SEPA salary file. Bizisy prepares payroll; it never calculates or files it.

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

Payroll overview#

POST/v1/payroll/overviewRead

Payroll at a glance (Bizisy prepares payroll; it never calculates or files it): the legal entities and the pay frequencies each may use (monthly everywhere; fortnightly and weekly in Great Britain and Ireland), each pay schedule, the current pay period of each entity (open, ended, locked, exported or acknowledged), the locked history, the export formats (the country's own first), the payslip rules per country and what needs attention. Read a period with payroll_periods_get. 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_overview on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

8 fields
  • entitiesobject[]required
    4 fields
    • idstringrequired
    • legal_namestringrequired
    • countrystringrequired
    • frequencies"monthly" | "fortnightly" | "weekly"[]required
  • schedulesobject[]required
    7 fields
    • legal_entity_idstringrequired
    • frequency"monthly" | "fortnightly" | "weekly"required
    • first_startstringrequired
    • pay_dayinteger | nullrequired
    • debtorobject | nullrequired
      3 fields
      • namestringrequired
      • ibanstringrequired
      • bicstring | nullrequired
    • datevobject | nullrequired
      2 fields
      • berater_nrstringrequired
      • mandanten_nrstringrequired
    • updated_atstringrequired
  • currentobject[]required
    9 fields
    • idstringrequired
    • legal_entityobjectrequired
      3 fields
      • idstringrequired
      • legal_namestringrequired
      • countrystringrequired
    • frequency"monthly" | "fortnightly" | "weekly"required
    • startstringrequired
    • endstringrequired
    • status"open" | "ended" | "locked" | "exported" | "acknowledged"required

      open: running; ended: its last day passed and it is not locked; locked; exported (at least one export); acknowledged (by the accountant).

    • locked_atstring | nullrequired
    • acknowledged_atstring | nullrequired
    • exportsintegerrequired
  • historyobject[]required
    9 fields
    • idstringrequired
    • legal_entityobjectrequired
      3 fields
      • idstringrequired
      • legal_namestringrequired
      • countrystringrequired
    • frequency"monthly" | "fortnightly" | "weekly"required
    • startstringrequired
    • endstringrequired
    • status"open" | "ended" | "locked" | "exported" | "acknowledged"required

      open: running; ended: its last day passed and it is not locked; locked; exported (at least one export); acknowledged (by the accountant).

    • locked_atstring | nullrequired
    • acknowledged_atstring | nullrequired
    • exportsintegerrequired
  • formatsobject[]required
    4 fields
    • idstringrequired
    • namestringrequired
    • descriptionstringrequired
    • countriesstring[]required
  • payslip_rulesobject[]required
    4 fields
    • countrystringrequired
    • delivery"electronic" | "opt_out"required
    • retentionstring | nullrequired
    • sourcestringrequired
  • unmatched_payslipsintegerrequired
  • canobjectrequired
    2 fields
    • managebooleanrequired
    • consentbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/overview \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "entities": [
      {
        "id": "e1",
        "legal_name": "Acme Lda",
        "country": "PT",
        "frequencies": [
          "monthly"
        ]
      }
    ],
    "schedules": [
      {
        "legal_entity_id": "e1",
        "frequency": "monthly",
        "first_start": "2026-03-01",
        "pay_day": 28,
        "debtor": {
          "name": "Acme Lda",
          "iban": "PT50000201231234567890154",
          "bic": "CGDIPTPL"
        },
        "datev": null,
        "updated_at": "2026-03-02T09:00:00.000Z"
      }
    ],
    "current": [
      {
        "id": "e1:2026-03-01",
        "legal_entity": {
          "id": "e1",
          "legal_name": "Acme Lda",
          "country": "PT"
        },
        "frequency": "monthly",
        "start": "2026-03-01",
        "end": "2026-03-31",
        "status": "ended",
        "locked_at": null,
        "acknowledged_at": null,
        "exports": 0
      }
    ],
    "history": [
      {
        "id": "e1:2026-02-01",
        "legal_entity": {
          "id": "e1",
          "legal_name": "Acme Lda",
          "country": "PT"
        },
        "frequency": "monthly",
        "start": "2026-02-01",
        "end": "2026-02-28",
        "status": "acknowledged",
        "locked_at": "2026-04-02T09:00:00.000Z",
        "acknowledged_at": "2026-03-03T10:00:00.000Z",
        "exports": 1
      }
    ],
    "formats": [
      {
        "id": "xlsx",
        "name": "Excel workbook",
        "description": "Every section on its own sheet.",
        "countries": []
      }
    ],
    "payslip_rules": [
      {
        "country": "PT",
        "delivery": "electronic",
        "retention": null,
        "source": "EU default."
      }
    ],
    "unmatched_payslips": 0,
    "can": {
      "manage": true,
      "consent": true
    }
  }
}

Set a pay schedule#

POST/v1/payroll/schedules.setWrite

Sets how a legal entity is paid: frequency (monthly; fortnightly or weekly only for entities in Great Britain or Ireland), first_start (the first period's first day; the 1st of a month for monthly) and pay_day (day of the month money arrives, optional). Also the company's bank account for the SEPA salary file (debtor: name, IBAN checked by its checksum, BIC optional) and the DATEV adviser and client numbers for the LODAS file. Frequency and first_start can't change once a period is locked. Owners, admins, HR and roles with Payroll at Edit, in the app only. 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. Pay schedules and the bank account are set in the app only.
MCP tool
payroll_schedules_set 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
  • frequency"monthly" | "fortnightly" | "weekly"

    Default "monthly".

  • first_startstringrequired

    Pattern ^\d{4}-\d{2}-\d{2}$.

  • pay_dayinteger | null

    From 1 to 31.

  • debtorobject | null
    3 fields
    • namestringrequired

      1–70 characters.

    • ibanstringrequired

      5–40 characters.

    • bicstring | null

      Up to 11 characters.

  • datevobject | null
    2 fields
    • berater_nrstringrequired

      Pattern ^\d{4,7}$.

    • mandanten_nrstringrequired

      Pattern ^\d{1,5}$.

Returns

7 fields
  • legal_entity_idstringrequired
  • frequency"monthly" | "fortnightly" | "weekly"required
  • first_startstringrequired
  • pay_dayinteger | nullrequired
  • debtorobject | nullrequired
    3 fields
    • namestringrequired
    • ibanstringrequired
    • bicstring | nullrequired
  • datevobject | nullrequired
    2 fields
    • berater_nrstringrequired
    • mandanten_nrstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/schedules.set \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "legal_entity_id": "e2",
  "frequency": "fortnightly",
  "first_start": "2026-03-02",
  "pay_day": null,
  "debtor": {
    "name": "Acme UK Ltd",
    "bic": "WESTGB2L"
  },
  "datev": null
}'
Response
{
  "data": {
    "legal_entity_id": "e1",
    "frequency": "fortnightly",
    "first_start": "2026-03-02",
    "pay_day": null,
    "debtor": {
      "name": "Acme Lda",
      "iban": "PT50000201231234567890154",
      "bic": "CGDIPTPL"
    },
    "datev": null,
    "updated_at": "2026-03-02T09:00:00.000Z"
  }
}

List pay items#

POST/v1/payroll/catalogue.listRead

The company's pay item catalogue: variable pay HR adds per period (bonus, overtime, commission, meal allowance, advance…) with kind (earning or deduction), unit (amount, hours or days) and a code per export target (DATEV wage type, BrightPay description). Archived items stay on earlier periods. 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_catalogue_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • itemsobject[]required
    6 fields
    • idstringrequired
    • namestringrequired
    • kind"earning" | "deduction"required
    • unit"amount" | "hours" | "days"required
    • codesobjectrequired
    • archivedbooleanrequired
  • maxintegerrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/catalogue.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "items": [
      {
        "id": "c1",
        "name": "Bonus",
        "kind": "earning",
        "unit": "amount",
        "codes": {
          "datev": "200",
          "brightpay": "Bonus"
        },
        "archived": false
      }
    ],
    "max": 100
  }
}

Add a pay item#

POST/v1/payroll/catalogue.addWrite

Adds a pay item to the catalogue: name (unique), kind (earning or deduction), unit (amount, hours or days) and codes per export target (pt_ru: the Relatório Único Anexo A column it counts in — sub_ref meal allowance, sub_turn shift allowance, out_sub other regular allowances, prest_ir irregular pay, r_supl overtime pay, horas_supl overtime hours). At most 100 items. 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_catalogue_add on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • namestringrequired

    1–60 characters.

  • kind"earning" | "deduction"

    Default "earning".

  • unit"amount" | "hours" | "days"

    Default "amount".

  • codesobject

    Codes per export target: datev (Lohnart, 1–4 digits), datev_bs (Bearbeitungsschlüssel; default 1 hours, 2 amount, 10 days), brightpay (the description BrightPay knows the item by), generic, staffology (Staffology pay code), xero_payroll (Xero earnings rate id, hours), silae (Silae variable element code), lexware (Lohnartnummer, 1–4 digits), sage50 (Sage 50 Payroll payment or deduction reference), meta4 (the Meta4 concept code; edited with the Meta4 codes).

    Default {}.

    11 fields
    • datevstringrequired

      Up to 40 characters.

    • datev_bsstringrequired

      Up to 40 characters.

    • brightpaystringrequired

      Up to 40 characters.

    • genericstringrequired

      Up to 40 characters.

    • staffologystringrequired

      Up to 40 characters.

    • xero_payrollstringrequired

      Up to 40 characters.

    • silaestringrequired

      Up to 40 characters.

    • lexwarestringrequired

      Up to 40 characters.

    • sage50stringrequired

      Up to 40 characters.

    • pt_rustringrequired

      Up to 40 characters.

    • meta4stringrequired

      Up to 40 characters.

Returns

  • idstringrequired
  • namestringrequired
  • kind"earning" | "deduction"required
  • unit"amount" | "hours" | "days"required
  • codesobjectrequired
  • archivedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/catalogue.add \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "Overtime",
  "kind": "earning",
  "unit": "hours",
  "codes": {
    "datev": "1100",
    "brightpay": "Overtime"
  }
}'
Response
{
  "data": {
    "id": "c1",
    "name": "Overtime",
    "kind": "earning",
    "unit": "hours",
    "codes": {
      "datev": "200",
      "brightpay": "Bonus"
    },
    "archived": false
  }
}

Change a pay item#

POST/v1/payroll/catalogue.updateWrite

Changes a pay item: name, kind, unit, codes (replaced whole) or archived (archived items cannot be added to new periods; earlier periods keep them). 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_catalogue_update on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • idstringrequired
  • namestring

    1–60 characters.

  • kind"earning" | "deduction"
  • unit"amount" | "hours" | "days"
  • codesobject

    Codes per export target: datev (Lohnart, 1–4 digits), datev_bs (Bearbeitungsschlüssel; default 1 hours, 2 amount, 10 days), brightpay (the description BrightPay knows the item by), generic, staffology (Staffology pay code), xero_payroll (Xero earnings rate id, hours), silae (Silae variable element code), lexware (Lohnartnummer, 1–4 digits), sage50 (Sage 50 Payroll payment or deduction reference), meta4 (the Meta4 concept code; edited with the Meta4 codes).

    11 fields
    • datevstringrequired

      Up to 40 characters.

    • datev_bsstringrequired

      Up to 40 characters.

    • brightpaystringrequired

      Up to 40 characters.

    • genericstringrequired

      Up to 40 characters.

    • staffologystringrequired

      Up to 40 characters.

    • xero_payrollstringrequired

      Up to 40 characters.

    • silaestringrequired

      Up to 40 characters.

    • lexwarestringrequired

      Up to 40 characters.

    • sage50stringrequired

      Up to 40 characters.

    • pt_rustringrequired

      Up to 40 characters.

    • meta4stringrequired

      Up to 40 characters.

  • archivedboolean

Returns

  • idstringrequired
  • namestringrequired
  • kind"earning" | "deduction"required
  • unit"amount" | "hours" | "days"required
  • codesobjectrequired
  • archivedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/catalogue.update \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"id":"c1","name":"Annual bonus","codes":{"datev":"201"}}'
Response
{
  "data": {
    "id": "c1",
    "name": "Annual bonus",
    "kind": "earning",
    "unit": "amount",
    "codes": {
      "datev": "200",
      "brightpay": "Bonus"
    },
    "archived": true
  }
}

Set an employee number#

POST/v1/payroll/people.set_numberWrite

Sets or clears a person's employee number (personnel number) for payroll providers: unique in the company, 1–20 letters, digits, dots, dashes or slashes (DATEV needs 1–5 digits). Owners, admins, HR and roles with Payroll at Edit, for the people they cover. 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_people_set_number 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

  • person_idstringrequired
  • employee_numberstring | nullrequired

    1–20 characters. Pattern ^[A-Za-z0-9._\-/]+$.

Returns

  • person_idstringrequired
  • employee_numberstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/people.set_number \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"person_id":"p2","employee_number":"1002"}'
Response
{
  "data": {
    "person_id": "p2",
    "employee_number": "1002"
  }
}

Number everyone without an employee number#

POST/v1/payroll/people.assign_numbersWrite

Gives every person of the current pay periods who has no employee number the next unused number (after the highest numeric one, from 1001). Owners, admins, HR and roles with Payroll at Edit that cover everyone. 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_people_assign_numbers on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

No input: send {}.

Returns

  • assignedintegerrequired
  • peopleobject[]required
    2 fields
    • person_idstringrequired
    • employee_numberstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/people.assign_numbers \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{}'
Response
{
  "data": {
    "assigned": 1,
    "people": [
      {
        "person_id": "p2",
        "employee_number": "1002"
      }
    ]
  }
}

Read a pay period#

POST/v1/payroll/periods.getRead

A pay period with its change set: people (master data, job, contract and pay at the period's end), entries by section (hire, leaver, job_change, pay_change, personal_change, late: each with effective_date and before → after per field), variable pay items, warnings (missing or invalid IBAN, tax id, social security number, employee number, contract data, pay), notes, comments, attachments, exports (format, SHA-256, who, when), payslips and net pay. An open period is live (it follows the data); a locked one is frozen. Custom roles see the people they cover; API keys and AI apps get pay and private values only with a consent (Payroll → Settings → Machine access), else they are null and listed in withheld. 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
Keys and apps
Pay and private values only with a consent (Payroll → Settings → Machine access); otherwise null and listed in withheld.
MCP tool
payroll_periods_get 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

14 fields
  • periodobjectrequired
    9 fields
    • idstringrequired
    • legal_entityobjectrequired
      3 fields
      • idstringrequired
      • legal_namestringrequired
      • countrystringrequired
    • frequency"monthly" | "fortnightly" | "weekly"required
    • startstringrequired
    • endstringrequired
    • status"open" | "ended" | "locked" | "exported" | "acknowledged"required

      open: running; ended: its last day passed and it is not locked; locked; exported (at least one export); acknowledged (by the accountant).

    • locked_atstring | nullrequired
    • acknowledged_atstring | nullrequired
    • exportsintegerrequired
  • previous_idstring | nullrequired
  • countrystringrequired
  • entity_namesobjectrequired

    Legal entity names by id (moves between entities).

  • change_setobjectrequired
    8 fields
    • first_exportbooleanrequired

      The entity's first period: everyone's details are listed for the payroll provider to set up.

    • peopleobject[]required
      23 fields
      • idstringrequired
      • namestringrequired
      • given_namestringrequired
      • family_namestringrequired
      • employee_numberstring | nullrequired
      • birthdaystring | nullrequired
      • addressstring | nullrequired
      • address_countrystring | nullrequired
      • tax_idstring | nullrequired
      • social_security_numberstring | nullrequired
      • ibanstring | nullrequired
      • start_datestring | nullrequired
      • end_datestring | nullrequired
      • titlestring | nullrequired
      • unitstring | nullrequired
      • locationstring | nullrequired
      • employment_typestring | nullrequired
      • ftenumber | nullrequired
      • contract_typestring | nullrequired
      • weekly_hoursnumber | nullrequired
      • payobject | nullrequired
        3 fields
        • amountnumberrequired
        • currencystringrequired
        • periodstringrequired
      • paper_payslipsbooleanrequired
      • in_periodbooleanrequired
    • entriesobject[]required
      7 fields
      • idstringrequired
      • section"hire" | "leaver" | "job_change" | "pay_change" | "personal_change" | "late"required
      • person_idstringrequired
      • effective_datestring | nullrequired
      • kind"hire" | "leaver" | "job_change" | "pay_change"required

        Late corrections: what came late.

      • changesobject[]required

        before → after per field; pay as "2400.00 EUR/month".

        3 fields
        • fieldstringrequired
        • beforestring | number | "null"required
        • afterstring | number | "null"required
      • late_ofstring | nullrequired

        Late corrections: the locked period they belong to.

    • itemsobject[]required
      11 fields
      • idstringrequired
      • person_idstringrequired
      • catalogue_idstringrequired
      • namestringrequired
      • kind"earning" | "deduction"required
      • unit"amount" | "hours" | "days"required
      • valuenumberrequired
      • currencystring | nullrequired
      • notestring | nullrequired
      • codesobjectrequired
      • source"hr" | "import" | "referral" | "benefit" | "comp"required

        benefit: from the benefits module (read-only here; changed in Benefits). comp: a salary review lump sum.

    • warningsobject[]required
      3 fields
      • codestring (enum)required

        One of: missing_iban, invalid_iban, missing_tax_id, invalid_tax_id, missing_ssn, invalid_ssn, missing_employee_number, missing_contract_type, missing_weekly_hours, missing_pay, missing_address, missing_birthday.

      • person_idstringrequired
      • messagestringrequired
    • absencesobject[]

      Only when the company uses Time off: approved time off inside the period (days counted inside it). Absent otherwise.

      8 fields
      • idstringrequired

        The time off booking.

      • person_idstringrequired
      • type_namestring | nullrequired

        The leave type; null for health leave when the caller has no consent for private data.

      • paidbooleanrequired
      • healthbooleanrequired

        Health leave (e.g. sick leave): special-category data.

      • fromstringrequired
      • tostringrequired

        Clipped to the period.

      • daysnumberrequired

        Working days inside the period (half-day precision).

    • untakenobject[]

      Only when the company uses Time off: leavers' leave balance at their last day (positive: days owed; negative: taken in advance).

      3 fields
      • person_idstringrequired
      • last_daystringrequired
      • daysnumberrequired
    • withheld"pay" | "private"[]required

      Values left out for this caller: API keys and AI apps get pay and private values only with a consent (Payroll → Settings → Machine access).

  • notesobject[]required
    3 fields
    • person_idstring | nullrequired
    • textstringrequired
    • updated_atstringrequired
  • commentsobject[]required
    5 fields
    • idstringrequired
    • authorstringrequired
    • minebooleanrequired
    • textstringrequired
    • created_atstringrequired
  • attachmentsobject[]required
    5 fields
    • idstringrequired
    • namestringrequired
    • sizeintegerrequired
    • content_typestringrequired
    • created_atstringrequired
  • exportsobject[]required
    7 fields
    • idstringrequired
    • formatstringrequired
    • filesobject[]required
      4 fields
      • namestringrequired
      • content_typestringrequired
      • sha256stringrequired
      • bytesintegerrequired
    • peopleintegerrequired
    • skippedintegerrequired
    • created_bystringrequired
    • created_atstringrequired
  • payslipsobject[]required
    8 fields
    • idstringrequired
    • namestringrequired
    • sizeintegerrequired
    • person_idstring | nullrequired
    • person_namestring | nullrequired
    • matched_by"tax_id" | "employee_number" | "name" | "manual"required
    • status"uploading" | "unmatched" | "published"required
    • created_atstringrequired
  • net_payobject[]required
    3 fields
    • person_idstringrequired
    • amountnumber | nullrequired
    • currencystringrequired
  • catalogueobject[]required
    6 fields
    • idstringrequired
    • namestringrequired
    • kind"earning" | "deduction"required
    • unit"amount" | "hours" | "days"required
    • codesobjectrequired
    • archivedbooleanrequired
  • pay_dayinteger | nullrequired
  • debtor_setbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/periods.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"period_id":"e1:2026-03-01"}'
Response
{
  "data": {
    "period": {
      "id": "e1:2026-03-01",
      "legal_entity": {
        "id": "e1",
        "legal_name": "Acme Lda",
        "country": "PT"
      },
      "frequency": "monthly",
      "start": "2026-03-01",
      "end": "2026-03-31",
      "status": "locked",
      "locked_at": "2026-04-02T09:00:00.000Z",
      "acknowledged_at": null,
      "exports": 0
    },
    "previous_id": "e1:2026-02-01",
    "country": "PT",
    "entity_names": {
      "e1": "Acme Lda"
    },
    "change_set": {
      "first_export": false,
      "people": [
        {
          "id": "p2",
          "name": "Bruno Costa",
          "given_name": "Bruno",
          "family_name": "Costa",
          "employee_number": "1002",
          "birthday": "1991-02-03",
          "address": "Rua das Flores 1, 1000-001 Lisboa, PT",
          "address_country": "PT",
          "tax_id": "123456789",
          "social_security_number": "12345678901",
          "iban": "PT50000201231234567890154",
          "start_date": "2026-03-10",
          "end_date": null,
          "title": "Engineer",
          "unit": "Platform",
          "location": "Lisbon",
          "employment_type": "full_time",
          "fte": 1,
          "contract_type": "permanent",
          "weekly_hours": 40,
          "pay": {
            "amount": 2400,
            "currency": "EUR",
            "period": "month"
          },
          "paper_payslips": false,
          "in_period": true
        }
      ],
      "entries": [
        {
          "id": "hire:p2:j2",
          "section": "hire",
          "person_id": "p2",
          "effective_date": "2026-03-10",
          "kind": null,
          "changes": [
            {
              "field": "start_date",
              "before": null,
              "after": "2026-03-10"
            },
            {
              "field": "pay",
              "before": null,
              "after": "2400.00 EUR/month"
            }
          ],
          "late_of": null
        }
      ],
      "items": [
        {
          "id": "i1",
          "person_id": "p2",
          "catalogue_id": "c1",
          "name": "Bonus",
          "kind": "earning",
          "unit": "amount",
          "value": 500,
          "currency": "EUR",
          "note": "Signing bonus",
          "codes": {
            "datev": "200"
          },
          "source": "hr"
        }
      ],
      "warnings": [
        {
          "code": "missing_employee_number",
          "person_id": "p2",
          "message": "No employee number."
        }
      ],
      "withheld": []
    },
    "notes": [
      {
        "person_id": null,
        "text": "Bonuses approved by the board on 20 March.",
        "updated_at": "2026-03-28T10:00:00.000Z"
      }
    ],
    "comments": [
      {
        "id": "cm1",
        "author": "Carla Contabilista",
        "mine": false,
        "text": "Received, running it on Monday.",
        "created_at": "2026-04-02T11:00:00.000Z"
      }
    ],
    "attachments": [
      {
        "id": "at1",
        "name": "overtime-march.pdf",
        "size": 20000,
        "content_type": "application/pdf",
        "created_at": "2026-03-30T10:00:00.000Z"
      }
    ],
    "exports": [
      {
        "id": "x1",
        "format": "xlsx",
        "files": [
          {
            "name": "payroll_Acme-Lda_2026-03-01_2026-03-31.xlsx",
            "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
            "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
            "bytes": 6120
          }
        ],
        "people": 12,
        "skipped": 0,
        "created_by": "u1",
        "created_at": "2026-04-02T10:00:00.000Z"
      }
    ],
    "payslips": [
      {
        "id": "s1",
        "name": "payslips-march.pdf (page 1)",
        "size": 48211,
        "person_id": "p2",
        "person_name": "Bruno Costa",
        "matched_by": "tax_id",
        "status": "published",
        "created_at": "2026-04-03T10:00:00.000Z"
      }
    ],
    "net_pay": [
      {
        "person_id": "p2",
        "amount": 1830.4,
        "currency": "EUR"
      }
    ],
    "catalogue": [
      {
        "id": "c1",
        "name": "Bonus",
        "kind": "earning",
        "unit": "amount",
        "codes": {
          "datev": "200",
          "brightpay": "Bonus"
        },
        "archived": false
      }
    ],
    "pay_day": 28,
    "debtor_set": true
  }
}

Lock a pay period#

POST/v1/payroll/periods.lockWrite

Locks the current pay period of a legal entity: its change set is frozen for export, and anything recorded later that takes effect within it goes into the next period as a late correction. Warnings do not stop a lock (the result counts them); read them first with payroll_periods_get. Preview with dry_run. Emits payroll.period.locked. Owners, admins, HR and roles with Payroll at Edit that cover everyone in the 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).

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

Input

  • period_idstringrequired

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

    12–120 characters.

Returns

  • periodobjectrequired
    9 fields
    • idstringrequired
    • legal_entityobjectrequired
      3 fields
      • idstringrequired
      • legal_namestringrequired
      • countrystringrequired
    • frequency"monthly" | "fortnightly" | "weekly"required
    • startstringrequired
    • endstringrequired
    • status"open" | "ended" | "locked" | "exported" | "acknowledged"required

      open: running; ended: its last day passed and it is not locked; locked; exported (at least one export); acknowledged (by the accountant).

    • locked_atstring | nullrequired
    • acknowledged_atstring | nullrequired
    • exportsintegerrequired
  • peopleintegerrequired
  • warningsintegerrequired
  • entriesintegerrequired
  • itemsintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/periods.lock \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"period_id":"e1:2026-03-01"}'
Response
{
  "data": {
    "period": {
      "id": "e1:2026-03-01",
      "legal_entity": {
        "id": "e1",
        "legal_name": "Acme Lda",
        "country": "PT"
      },
      "frequency": "monthly",
      "start": "2026-03-01",
      "end": "2026-03-31",
      "status": "locked",
      "locked_at": "2026-04-02T09:00:00.000Z",
      "acknowledged_at": null,
      "exports": 0
    },
    "people": 12,
    "warnings": 3,
    "entries": 5,
    "items": 4
  }
}

Unlock a pay period#

POST/v1/payroll/periods.unlockWrite

Unlocks the most recently locked period of a legal entity, while nothing was taken from it yet (no export, send to a payroll tool, accountant acknowledgement, payslip or net pay): it is live again. Once something was exported, corrections go into the next period instead. Owners, admins, HR and roles with Payroll at Edit that cover everyone in the 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).

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

Input

  • period_idstringrequired

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

    12–120 characters.

Returns

  • periodobjectrequired
    9 fields
    • idstringrequired
    • legal_entityobjectrequired
      3 fields
      • idstringrequired
      • legal_namestringrequired
      • countrystringrequired
    • frequency"monthly" | "fortnightly" | "weekly"required
    • startstringrequired
    • endstringrequired
    • status"open" | "ended" | "locked" | "exported" | "acknowledged"required

      open: running; ended: its last day passed and it is not locked; locked; exported (at least one export); acknowledged (by the accountant).

    • locked_atstring | nullrequired
    • acknowledged_atstring | nullrequired
    • exportsintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/periods.unlock \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"period_id":"e1:2026-03-01"}'
Response
{
  "data": {
    "period": {
      "id": "e1:2026-03-01",
      "legal_entity": {
        "id": "e1",
        "legal_name": "Acme Lda",
        "country": "PT"
      },
      "frequency": "monthly",
      "start": "2026-03-01",
      "end": "2026-03-31",
      "status": "ended",
      "locked_at": null,
      "acknowledged_at": null,
      "exports": 0
    }
  }
}

Acknowledge a pay period#

POST/v1/payroll/periods.acknowledgeWrite

Confirms a locked period was received (the accountant or payroll bureau says so); HR sees who and when. 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).

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

Input

  • period_idstringrequired

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

    12–120 characters.

Returns

  • periodobjectrequired
    9 fields
    • idstringrequired
    • legal_entityobjectrequired
      3 fields
      • idstringrequired
      • legal_namestringrequired
      • countrystringrequired
    • frequency"monthly" | "fortnightly" | "weekly"required
    • startstringrequired
    • endstringrequired
    • status"open" | "ended" | "locked" | "exported" | "acknowledged"required

      open: running; ended: its last day passed and it is not locked; locked; exported (at least one export); acknowledged (by the accountant).

    • locked_atstring | nullrequired
    • acknowledged_atstring | nullrequired
    • exportsintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/periods.acknowledge \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"period_id":"e1:2026-03-01"}'
Response
{
  "data": {
    "period": {
      "id": "e1:2026-03-01",
      "legal_entity": {
        "id": "e1",
        "legal_name": "Acme Lda",
        "country": "PT"
      },
      "frequency": "monthly",
      "start": "2026-03-01",
      "end": "2026-03-31",
      "status": "acknowledged",
      "locked_at": "2026-04-02T09:00:00.000Z",
      "acknowledged_at": "2026-04-03T10:00:00.000Z",
      "exports": 0
    }
  }
}

Add variable pay#

POST/v1/payroll/items.addWrite

Adds a variable pay item for one person in an open period: catalogue_id (payroll_catalogue_list), value (an amount for amount items, else hours or days; at most 2 decimals), currency (amount items; default the person's pay currency, else EUR) and an optional note for the accountant. At most 5000 items per period. Owners, admins, HR and roles with Payroll at Edit, for the people they cover. 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_items_add 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.

  • person_idstringrequired
  • catalogue_idstringrequired
  • valuenumberrequired

    From -10000000 to 10000000.

  • currencystring

    Pattern ^[A-Z]{3}$.

  • notestring

    Up to 300 characters.

Returns

7 fields
  • idstringrequired
  • period_idstringrequired
  • person_idstringrequired
  • catalogue_idstringrequired
  • valuenumberrequired
  • currencystring | nullrequired
  • notestring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/items.add \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "period_id": "e1:2026-03-01",
  "person_id": "p2",
  "catalogue_id": "c1",
  "value": 500,
  "currency": "EUR",
  "note": "Signing bonus"
}'
Response
{
  "data": {
    "id": "i1",
    "period_id": "e1:2026-03-01",
    "person_id": "p2",
    "catalogue_id": "c1",
    "value": 500,
    "currency": "EUR",
    "note": "Signing bonus"
  }
}

Remove variable pay#

POST/v1/payroll/items.removeDestructive

Removes a variable pay item from an open period. Owners, admins, HR and roles with Payroll at Edit, for the people they cover. 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_items_remove on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • item_idstringrequired

Returns

  • idstringrequired
  • period_idstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/items.remove \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"item_id":"i1"}'
Response
{
  "data": {
    "id": "i1",
    "period_id": "e1:2026-03-01"
  }
}

Import variable pay#

POST/v1/payroll/items.importWrite

Adds many variable pay items to an open period at once (a CSV read by the app, or rows from your system): each row names the person (person_id, employee_number, tax_id or exact full name), the item (catalogue name or code), value, optional currency and note. All or nothing: any row that can't be matched refuses the whole import with the row numbers (preview with dry_run). An API key or AI app without consent for private data names people by person_id or employee_number only. At most 2000 rows. Owners, admins, HR and roles with Payroll at Edit that cover everyone. 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
Names people by person id or employee number only, unless a consent covers private data.
MCP tool
payroll_items_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

  • period_idstringrequired

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

    12–120 characters.

  • rowsobject[]required

    1–2000 items.

    8 fields
    • person_idstring

      Up to 64 characters.

    • employee_numberstring

      Up to 20 characters.

    • tax_idstring

      Up to 40 characters.

    • namestring

      Up to 200 characters.

    • itemstringrequired

      The pay item's name or one of its codes.

      1–60 characters.

    • valuenumberrequired

      From -10000000 to 10000000.

    • currencystring

      Pattern ^[A-Z]{3}$.

    • notestring

      Up to 300 characters.

Returns

  • period_idstringrequired
  • addedintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/items.import \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "period_id": "e1:2026-03-01",
  "rows": [
    {
      "employee_number": "1002",
      "item": "Bonus",
      "value": 500
    },
    {
      "name": "Bruno Costa",
      "item": "200",
      "value": 50,
      "note": "Meal allowance"
    }
  ]
}'
Response
{
  "data": {
    "period_id": "e1:2026-03-01",
    "added": 2
  }
}

Write a note for the accountant#

POST/v1/payroll/notes.setWrite

Sets the note of an open period for the accountant: for the whole period (person_id null) or one person. Empty text removes it. Notes go into the exports. Owners, admins, HR and roles with Payroll at Edit, for the people they cover. 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_notes_set 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.

  • person_idstring | null

    Default null.

  • textstringrequired

    Up to 2000 characters.

Returns

  • period_idstringrequired
  • person_idstring | nullrequired
  • textstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/notes.set \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "period_id": "e1:2026-03-01",
  "person_id": "p2",
  "text": "Starts on the 10th."
}'
Response
{
  "data": {
    "period_id": "e1:2026-03-01",
    "person_id": null,
    "text": "Starts on the 10th."
  }
}

Comment on a pay period#

POST/v1/payroll/comments.addWrite

Adds a comment to a pay period (open or locked): HR and the accountant talk there. At most 500 per period. 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).

Who can call it
Manage key owner admin hr
MCP tool
payroll_comments_add 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.

  • textstringrequired

    1–2000 characters.

Returns

  • idstringrequired
  • authorstringrequired
  • minebooleanrequired
  • textstringrequired
  • created_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/comments.add \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"period_id":"e1:2026-03-01","text":"Received, running it on Monday."}'
Response
{
  "data": {
    "id": "cm1",
    "author": "Carla Contabilista",
    "mine": true,
    "text": "Received, running it on Monday.",
    "created_at": "2026-04-02T11:00:00.000Z"
  }
}

Export a pay period#

POST/v1/payroll/exports.createWrite

Exports a locked pay period for the payroll provider: format xlsx (every section on its own sheet), csv, json (bizisy.payroll-change-set.v1), datev_lodas (DATEV LODAS ASCII: personnel numbers, names and variable pay with DATEV wage types) brightpay_csv (BrightPay additions and deductions), lexware_lohn (Lexware lohn+gehalt pay data and master data), sage50_csv (Sage 50 Payroll payments and deductions, hours and rates) or silae_csv (Silae variable data). Returns the files (UTF-8 text or base64) and records each file's SHA-256, who and when; skipped lists what a format could not carry. Emits payroll.export.created. Custom roles export the people they cover. API keys and AI apps need a consent for pay and private data (Payroll → Settings → Machine access). 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).

Who can call it
Manage key owner admin hr
Keys and apps
Needs a consent for pay and private data (Payroll → Settings → Machine access).
MCP tool
payroll_exports_create 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.

  • formatstring (enum)required

    meta4: the file Meta4 loads with its bulk-load template, with the company's Meta4 codes.

    One of: xlsx, csv, json, datev_lodas, brightpay_csv, lexware_lohn, sage50_csv, silae_csv, meta4.

Returns

  • exportobjectrequired
    7 fields
    • idstringrequired
    • formatstringrequired
    • filesobject[]required
      4 fields
      • namestringrequired
      • content_typestringrequired
      • sha256stringrequired
      • bytesintegerrequired
    • peopleintegerrequired
    • skippedintegerrequired
    • created_bystringrequired
    • created_atstringrequired
  • filesobject[]required
    6 fields
    • namestringrequired
    • content_typestringrequired
    • sha256stringrequired
    • bytesintegerrequired
    • encoding"utf8" | "base64"required
    • contentstringrequired

      The file: UTF-8 text, or base64 for binary files (XLSX, Windows-1252 DATEV text).

  • skippedobject[]required
    3 fields
    • person_idstring | nullrequired
    • item_idstring | nullrequired
    • reasonstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/exports.create \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"period_id":"e1:2026-03-01","format":"datev_lodas"}'
Response
{
  "data": {
    "export": {
      "id": "x1",
      "format": "xlsx",
      "files": [
        {
          "name": "payroll_Acme-Lda_2026-03-01_2026-03-31.xlsx",
          "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
          "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
          "bytes": 6120
        }
      ],
      "people": 12,
      "skipped": 0,
      "created_by": "u1",
      "created_at": "2026-04-02T10:00:00.000Z"
    },
    "files": [
      {
        "name": "payroll_Acme-Lda_2026-03-01_2026-03-31.csv",
        "content_type": "text/csv",
        "sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
        "bytes": 120,
        "encoding": "utf8",
        "content": "section,employee_number,name\r\n"
      }
    ],
    "skipped": []
  }
}

Download an export again#

POST/v1/payroll/exports.downloadWrite

Downloads an earlier export of a locked period again: the files are made again from the frozen period and checked against the SHA-256 recorded when it was created (matches false: someone in it was erased since). SEPA salary files are not kept: create a new one. Recorded in Activity. Custom roles only when the export covers people they cover; API keys and AI apps need a consent for pay and private data.

Who can call it
Manage key owner admin hr
Keys and apps
Needs a consent for pay and private data.
MCP tool
payroll_exports_download 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

  • export_idstringrequired

Returns

  • exportobjectrequired
    7 fields
    • idstringrequired
    • formatstringrequired
    • filesobject[]required
      4 fields
      • namestringrequired
      • content_typestringrequired
      • sha256stringrequired
      • bytesintegerrequired
    • peopleintegerrequired
    • skippedintegerrequired
    • created_bystringrequired
    • created_atstringrequired
  • filesobject[]required
    6 fields
    • namestringrequired
    • content_typestringrequired
    • sha256stringrequired
    • bytesintegerrequired
    • encoding"utf8" | "base64"required
    • contentstringrequired

      The file: UTF-8 text, or base64 for binary files (XLSX, Windows-1252 DATEV text).

  • matchesbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/exports.download \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"export_id":"x1"}'
Response
{
  "data": {
    "export": {
      "id": "x1",
      "format": "xlsx",
      "files": [
        {
          "name": "payroll_Acme-Lda_2026-03-01_2026-03-31.xlsx",
          "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
          "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
          "bytes": 6120
        }
      ],
      "people": 12,
      "skipped": 0,
      "created_by": "u1",
      "created_at": "2026-04-02T10:00:00.000Z"
    },
    "files": [
      {
        "name": "payroll_Acme-Lda_2026-03-01_2026-03-31.csv",
        "content_type": "text/csv",
        "sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
        "bytes": 120,
        "encoding": "utf8",
        "content": "section,employee_number,name\r\n"
      }
    ],
    "matches": true
  }
}

Import net pay#

POST/v1/payroll/net_pay.importWrite

Records each person's net pay for a locked period from the payroll provider's results (a CSV read by the app, or rows from your system): rows name the person (person_id, employee_number, tax_id or exact full name) with amount and currency (default EUR). Replaces the period's net pay. All or nothing: unmatched rows refuse the import with their row numbers (preview with dry_run). An API key or AI app without consent for private data names people by person_id or employee_number only. Used for the SEPA salary file. At most 5000 rows. API keys and AI apps need a consent for pay data. Owners, admins, HR and roles with Payroll that cover everyone. 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
Needs a consent for pay data; names people by person id or employee number only, unless the consent covers private data.
MCP tool
payroll_net_pay_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

  • period_idstringrequired

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

    12–120 characters.

  • rowsobject[]required

    1–5000 items.

    6 fields
    • person_idstring

      Up to 64 characters.

    • employee_numberstring

      Up to 20 characters.

    • tax_idstring

      Up to 40 characters.

    • namestring

      Up to 200 characters.

    • amountnumberrequired

      From 0 to 10000000.

    • currencystring

      Pattern ^[A-Z]{3}$.

Returns

  • period_idstringrequired
  • recordedintegerrequired
  • totalobject[]required
    2 fields
    • currencystringrequired
    • amountnumberrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/net_pay.import \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "period_id": "e1:2026-03-01",
  "rows": [
    {
      "employee_number": "1002",
      "amount": 1830.4
    },
    {
      "name": "Bruno Costa",
      "amount": 1830.4,
      "currency": "EUR"
    }
  ]
}'
Response
{
  "data": {
    "period_id": "e1:2026-03-01",
    "recorded": 12,
    "total": [
      {
        "currency": "EUR",
        "amount": 21960.8
      }
    ]
  }
}

Clear net pay#

POST/v1/payroll/net_pay.clearDestructive

Removes a locked period's net pay (to import it again). Owners, admins, HR and roles with Payroll that cover everyone. 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_net_pay_clear on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • period_idstringrequired

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

    12–120 characters.

Returns

  • period_idstringrequired
  • removedintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/net_pay.clear \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"period_id":"e1:2026-03-01"}'
Response
{
  "data": {
    "period_id": "e1:2026-03-01",
    "removed": 12
  }
}

Create a SEPA salary file#

POST/v1/payroll/sepa.createWrite

Creates a SEPA credit transfer file (ISO 20022 pain.001.001.09, category purpose SALA, batch booking) paying each person's imported net pay from the legal entity's account (Payroll settings) on execution_date, to the IBAN each person has now. People without a valid IBAN, a name, a euro amount above zero are left out and listed in problems. Upload the file to your bank; Bizisy never moves money. The file's SHA-256, who and when are recorded; the file itself is not kept. In the app only. Owners, admins, HR and roles with Payroll at Edit that cover everyone in the 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. The SEPA salary file is made in the app only.
MCP tool
payroll_sepa_create 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.

  • execution_datestringrequired

    Pattern ^\d{4}-\d{2}-\d{2}$.

Returns

  • exportobject | nullrequired
    7 fields
    • idstringrequired
    • formatstringrequired
    • filesobject[]required
      4 fields
      • namestringrequired
      • content_typestringrequired
      • sha256stringrequired
      • bytesintegerrequired
    • peopleintegerrequired
    • skippedintegerrequired
    • created_bystringrequired
    • created_atstringrequired
  • fileobject | nullrequired
    6 fields
    • namestringrequired
    • content_typestringrequired
    • sha256stringrequired
    • bytesintegerrequired
    • encoding"utf8" | "base64"required
    • contentstringrequired

      The file: UTF-8 text, or base64 for binary files (XLSX, Windows-1252 DATEV text).

  • paymentsintegerrequired
  • totalnumberrequired
  • problemsobject[]required
    3 fields
    • person_idstring | nullrequired
    • codestringrequired
    • messagestringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/sepa.create \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"period_id":"e1:2026-03-01","execution_date":"2026-04-28"}'
Response
{
  "data": {
    "export": {
      "id": "x1",
      "format": "sepa_pain001",
      "files": [
        {
          "name": "payroll_Acme-Lda_2026-03-01_2026-03-31.xlsx",
          "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
          "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
          "bytes": 6120
        }
      ],
      "people": 12,
      "skipped": 0,
      "created_by": "u1",
      "created_at": "2026-04-02T10:00:00.000Z"
    },
    "file": {
      "name": "salaries_2026-03-01_2026-03-31.xml",
      "content_type": "application/xml",
      "sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
      "bytes": 120,
      "encoding": "utf8",
      "content": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>"
    },
    "payments": 11,
    "total": 20130.4,
    "problems": [
      {
        "person_id": "p9",
        "code": "missing_iban",
        "message": "No IBAN: left out of the file."
      }
    ]
  }
}

My payroll companies#

POST/v1/payroll/workspaceRead

The companies you prepare or run payroll for with this account (yours, or outside access such as an accountant's clients): per company its address, your role and the state of its pay periods (open, ended and not locked, locked, exported, acknowledged). No people or amounts. Open a company on its own address to work on it. Needs Payroll in this company; an API key or AI app gets only this company. 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
Keys and apps
Only the company the key or app belongs to.
MCP tool
payroll_workspace on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • companiesobject[]required
    9 fields
    • org_idstringrequired
    • namestringrequired
    • urlstringrequired
    • rolestringrequired
    • externalbooleanrequired
    • access_untilstring | nullrequired
    • currentbooleanrequired
    • periodsobject[]required

      Per pay schedule: the current period, and the last locked one when it still waits for an export or acknowledgement.

      3 fields
      • startstringrequired
      • endstringrequired
      • status"open" | "ended" | "locked" | "exported" | "acknowledged"required
    • set_upbooleanrequired

      The company has a pay schedule.

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/workspace \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "companies": [
      {
        "org_id": "o1",
        "name": "Acme Lda",
        "url": "https://acme.bizisy.com/manage/payroll",
        "role": "Accountant",
        "external": true,
        "access_until": null,
        "current": true,
        "periods": [
          {
            "start": "2026-03-01",
            "end": "2026-03-31",
            "status": "exported"
          }
        ],
        "set_up": true
      }
    ]
  }
}

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

Developer docs