Skip to content

API reference

Payslips and attachments

Upload payslips for a locked period (they become the person's documents), match the ones left over, and files for the accountant.

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

Record a person's payslip choice#

POST/v1/payroll/payslip_delivery.setWrite

Records whether a person wants their payslips on paper (they asked HR). Their payslips are then kept as HR's copy and listed to hand over on paper. In France employees may refuse electronic payslips at any time (Code du travail L3243-2). 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_payslip_delivery_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

  • person_idstringrequired
  • paperbooleanrequired

Returns

  • person_idstringrequired
  • paperbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

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

My payslip choice#

POST/v1/payroll/me.payslip_delivery.getRead

Whether your payslips come in Bizisy (your documents) or you asked for paper, and the rule where you work. 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
Me key anyone
MCP tool
payroll_me_payslip_delivery_get on My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • appliesbooleanrequired

    Your company prepares payroll in Bizisy for your legal entity.

  • paperbooleanrequired
  • countrystring | nullrequired
  • delivery"electronic" | "opt_out"required
  • retentionstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/me.payslip_delivery.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "applies": true,
    "paper": false,
    "country": "PT",
    "delivery": "electronic",
    "retention": null
  }
}

Ask for paper payslips#

POST/v1/payroll/me.payslip_delivery.setWrite

Asks for your payslips on paper (paper true) or back in Bizisy (false). HR keeps a copy either way and hands paper ones over. 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
Me key anyone
MCP tool
payroll_me_payslip_delivery_set on My Workplace
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • paperbooleanrequired

Returns

  • appliesbooleanrequired

    Your company prepares payroll in Bizisy for your legal entity.

  • paperbooleanrequired
  • countrystring | nullrequired
  • delivery"electronic" | "opt_out"required
  • retentionstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/me.payslip_delivery.set \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"paper":true}'
Response
{
  "data": {
    "applies": true,
    "paper": true,
    "country": "PT",
    "delivery": "electronic",
    "retention": null
  }
}

Start uploading payslips#

POST/v1/payroll/payslips.startWrite

Uploads payslips for a locked period in three steps: (1) this call with up to 5 PDF files (name, size, sha256 and the person each is for, or null); (2) PUT each file to its signed URL within 15 minutes with exactly the returned headers; (3) payroll_payslips_finish. Matched payslips go to the person's documents (category Payslip; HR's copy only when they asked for paper) and they are told; unmatched ones wait for HR (payroll_payslips_assign). PDF only, at most 10 MB each, 2000 per period. API keys and AI apps need a consent for pay data. Owners, admins, HR and roles with Payroll, 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
Keys and apps
Needs a consent for pay data.
MCP tool
payroll_payslips_start 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.

  • filesobject[]required

    1–5 items.

    5 fields
    • namestringrequired

      1–200 characters.

    • sizeintegerrequired

      At least 0.

    • sha256stringrequired

      Pattern ^[0-9a-f]{64}$.

    • person_idstring | nullrequired

      The person this payslip is for, or null to keep it unmatched for HR to assign.

    • matched_by"tax_id" | "employee_number" | "name" | "manual"

      Default null.

Returns

  • uploadsobject[]required
    3 fields
    • payslip_idstringrequired
    • uploadobject | nullrequired
      4 fields
      • urlstringrequired
      • method"PUT"required
      • headersobjectrequired
      • resumablefalserequired
    • expires_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/payslips.start \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "period_id": "e1:2026-03-01",
  "files": [
    {
      "name": "payslip-bruno.pdf",
      "size": 48211,
      "sha256": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
      "person_id": "p2",
      "matched_by": "tax_id"
    }
  ]
}'
Response
{
  "data": {
    "uploads": [
      {
        "payslip_id": "s1",
        "upload": {
          "url": "https://storage.example/upload",
          "method": "PUT",
          "headers": {
            "content-type": "application/pdf"
          },
          "resumable": false
        },
        "expires_at": "2026-04-03T10:15:00.000Z"
      }
    ]
  }
}

Finish uploading payslips#

POST/v1/payroll/payslips.finishWrite

Finishes payslip uploads (payroll_payslips_start): each file is checked (size, SHA-256, a real PDF); matched ones are published to the person's documents and the person is told; unmatched ones wait for HR. A file that does not match what was started is refused and deleted. API keys and AI apps need a consent for pay data. Owners, admins, HR and roles with Payroll, 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
Keys and apps
Needs a consent for pay data.
MCP tool
payroll_payslips_finish 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

  • payslip_idsstring[]required

    1–5 items.

Returns

  • 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
  • publishedintegerrequired
  • unmatchedintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/payslips.finish \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"payslip_ids":["s1"]}'
Response
{
  "data": {
    "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"
      }
    ],
    "published": 1,
    "unmatched": 0
  }
}

Assign a payslip#

POST/v1/payroll/payslips.assignWrite

Gives an unmatched payslip to a person of its period: it is published to their documents and they are told. Owners, admins, HR and roles with Payroll, 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_payslips_assign 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

  • payslip_idstringrequired
  • person_idstringrequired

Returns

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

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/payslips.assign \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"payslip_id":"s1","person_id":"p2"}'
Response
{
  "data": {
    "id": "s1",
    "name": "payslips-march.pdf (page 1)",
    "size": 48211,
    "person_id": "p2",
    "person_name": "Bruno Costa",
    "matched_by": "manual",
    "status": "published",
    "created_at": "2026-04-03T10:00:00.000Z"
  }
}

Discard a payslip#

POST/v1/payroll/payslips.discardDestructive

Deletes an unmatched payslip and its file (one that belongs to nobody, or was uploaded twice). Published payslips are documents: delete them there. 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_payslips_discard on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • payslip_idstringrequired

Returns

  • idstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/payslips.discard \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"payslip_id":"s1"}'
Response
{
  "data": {
    "id": "s1"
  }
}

Open an unmatched payslip#

POST/v1/payroll/payslips.downloadWrite

A 5-minute link to an unmatched payslip, to see whose it is before assigning it. Recorded in Activity. In the app only. Owners, admins, HR and roles with Payroll that cover everyone.

Web app only
Refused for API keys and connected apps. Unmatched payslips are opened in the app only.
MCP tool
payroll_payslips_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

  • payslip_idstringrequired

Returns

  • urlstring | nullrequired
  • expires_atstring | nullrequired
  • namestringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/payslips.download \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"payslip_id":"s1"}'
Response
{
  "data": {
    "url": "https://storage.example/download",
    "expires_at": "2026-04-03T10:05:00.000Z",
    "name": "payslips-march.pdf (page 4)"
  }
}

Attach a file to a pay period#

POST/v1/payroll/attachments.startWrite

Attaches a file for the accountant to a pay period (timesheets, a bonus decision): (1) this call with the file's name, size, content_type and sha256; (2) PUT the bytes to the signed URL; (3) payroll_attachments_finish. Accepted: PDF, images, Word, Excel, OpenDocument, text and CSV (checked from the bytes). At most 20 per period. 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_attachments_start 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.

  • fileobjectrequired
    4 fields
    • namestringrequired

      1–200 characters.

    • sizeintegerrequired

      At least 0.

    • sha256stringrequired

      Pattern ^[0-9a-f]{64}$.

    • content_typestringrequired

      1–200 characters.

Returns

  • attachment_idstringrequired
  • uploadobject | nullrequired
    4 fields
    • urlstringrequired
    • method"PUT"required
    • headersobjectrequired
    • resumablefalserequired
  • expires_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/attachments.start \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "period_id": "e1:2026-03-01",
  "file": {
    "name": "overtime-march.pdf",
    "size": 20000,
    "sha256": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
    "content_type": "application/pdf"
  }
}'
Response
{
  "data": {
    "attachment_id": "at1",
    "upload": {
      "url": "https://storage.example/upload",
      "method": "PUT",
      "headers": {
        "content-type": "application/pdf"
      },
      "resumable": false
    },
    "expires_at": "2026-03-30T10:15:00.000Z"
  }
}

Finish attaching a file#

POST/v1/payroll/attachments.finishWrite

Finishes an attachment upload (payroll_attachments_start): the bytes are checked, then the accountant sees it on the period. 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_attachments_finish 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

  • attachment_idstringrequired

Returns

  • idstringrequired
  • namestringrequired
  • sizeintegerrequired
  • content_typestringrequired
  • created_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/attachments.finish \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"attachment_id":"at1"}'
Response
{
  "data": {
    "id": "at1",
    "name": "overtime-march.pdf",
    "size": 20000,
    "content_type": "application/pdf",
    "created_at": "2026-03-30T10:00:00.000Z"
  }
}

Download a pay period's attachment#

POST/v1/payroll/attachments.downloadWrite

A 5-minute link that downloads an attachment of a pay period. Recorded in Activity. API keys and AI apps need a consent for pay and private data. Owners, admins, HR and roles with Payroll that cover everyone (attachments may be about anyone in the period).

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

  • attachment_idstringrequired

Returns

  • urlstring | nullrequired
  • expires_atstring | nullrequired
  • namestringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/attachments.download \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"attachment_id":"at1"}'
Response
{
  "data": {
    "url": "https://storage.example/download",
    "expires_at": "2026-03-30T10:05:00.000Z",
    "name": "overtime-march.pdf"
  }
}

Remove a pay period's attachment#

POST/v1/payroll/attachments.removeDestructive

Deletes an attachment and its file. 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_attachments_remove on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • attachment_idstringrequired

Returns

  • idstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/attachments.remove \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"attachment_id":"at1"}'
Response
{
  "data": {
    "id": "at1"
  }
}

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

Developer docs