Skip to content

API reference

Meta4 bridge

The codes Meta4 knows each leave type, pay item, time-clock total, leaving reason and contract type by (matched from a pasted code list), the preview of a locked period before its Meta4 file is made (payroll_exports_create, format meta4), and the reconciliation with Meta4's results.

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

Preview a period for Meta4#

POST/v1/payroll/meta4.previewRead

Before downloading a locked period's Meta4 file: the lines per section (hires, leavers, job and pay changes, variable pay, time-clock totals, absences, late corrections), the problems first (people without an employee number, rows without a Meta4 code, starter codes still to confirm; each says how to fix it), and how it compares with the last Meta4 export of the period (the same, or how many lines changed). Nothing is written. Custom roles see the people they cover. API keys and AI apps need a consent for pay and private data. 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_meta4_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.

Returns

  • period_idstringrequired
  • linesintegerrequired
  • sectionsobject[]required
    2 fields
    • sectionstring (enum)required

      One of: hires, leavers, changes, pay, items, time, absences, late.

    • linesintegerrequired
  • problemsobject[]required
    5 fields
    • kind"no_number" | "no_code" | "to_confirm" | "open_month"required
    • person_idstring | nullrequired
    • code_rowstring | nullrequired
    • countintegerrequired
    • messagestringrequired
  • lastobject | nullrequired
    4 fields
    • export_idstringrequired
    • created_atstringrequired
    • samebooleanrequired
    • changedintegerrequired

      Lines added, removed or changed since that export.

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/meta4.preview \
  -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",
    "lines": 4,
    "sections": [
      {
        "section": "hires",
        "lines": 1
      },
      {
        "section": "leavers",
        "lines": 0
      },
      {
        "section": "changes",
        "lines": 0
      },
      {
        "section": "pay",
        "lines": 0
      },
      {
        "section": "items",
        "lines": 2
      },
      {
        "section": "time",
        "lines": 0
      },
      {
        "section": "absences",
        "lines": 1
      },
      {
        "section": "late",
        "lines": 0
      }
    ],
    "problems": [
      {
        "kind": "to_confirm",
        "person_id": null,
        "code_row": "pay:base",
        "count": 1,
        "message": "Base pay uses Bizisy's starter code VB: confirm it is your Meta4 code."
      }
    ],
    "last": {
      "export_id": "x1",
      "created_at": "2026-04-02T10:00:00.000Z",
      "same": false,
      "changed": 1
    }
  }
}

Get the Meta4 codes#

POST/v1/payroll/code_map.getRead

The codes Meta4 (the payroll tool) knows each Bizisy thing by, one row each: the company's leave types and pay items, time-clock totals (overtime on a working day, rest day or holiday; night hours; days without a record), base pay, leaving reasons and contract types. Each row has its code and a status: confirmed, to_confirm (Bizisy's starter code for the country: a placeholder, since Meta4 codes are each company's own) or missing. 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_code_map_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • tool"meta4"

    Default "meta4".

Returns

  • tool"meta4"required
  • countrystringrequired
  • rowsobject[]required
    7 fields
    • group"leave" | "items" | "time" | "pay" | "leaving" | "contract"required
    • keystringrequired
    • labelstringrequired
    • unit"days" | "hours" | "amount"required
    • codestring | nullrequired

      The code sent to the payroll tool (null: none yet).

    • status"confirmed" | "to_confirm" | "missing"required

      confirmed: HR set or confirmed it; to_confirm: Bizisy's starter code, a placeholder; missing: no code (rows of this kind are listed as problems in the export).

    • descriptionstring | nullrequired

      The tool's description of the code, from a pasted code list.

  • countsobjectrequired
    3 fields
    • confirmedintegerrequired
    • to_confirmintegerrequired
    • missingintegerrequired
  • updated_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/code_map.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"meta4"}'
Response
{
  "data": {
    "tool": "meta4",
    "country": "PT",
    "updated_at": "2026-11-14T10:00:00.000Z",
    "counts": {
      "confirmed": 1,
      "to_confirm": 1,
      "missing": 1
    },
    "rows": [
      {
        "group": "leave",
        "key": "vacation",
        "label": "Holidays",
        "unit": "days",
        "code": "F01",
        "status": "confirmed",
        "description": "Férias"
      },
      {
        "group": "items",
        "key": "c1",
        "label": "Bonus",
        "unit": "amount",
        "code": null,
        "status": "missing",
        "description": null
      },
      {
        "group": "pay",
        "key": "base",
        "label": "Base pay",
        "unit": "amount",
        "code": "VB",
        "status": "to_confirm",
        "description": null
      }
    ]
  }
}

Set Meta4 codes#

POST/v1/payroll/code_map.setWrite

Sets the Meta4 code of rows of the code map (group and key from payroll_code_map_get; code null: no code). Rows not sent keep theirs; confirm = send the starter code. Pay item codes are kept on the pay item (catalogue). Locked periods' exports keep the codes they were made with. At most 2000 rows. 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_code_map_set on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • tool"meta4"

    Default "meta4".

  • rowsobject[]required

    1–2000 items.

    4 fields
    • group"leave" | "items" | "time" | "pay" | "leaving" | "contract"required
    • keystringrequired

      1–64 characters.

    • codestring | nullrequired

      1–40 characters. Pattern ^[^\s;,"=+@\t\r\n][^;"\t\r\n]{0,39}$.

    • descriptionstring | null

      Up to 120 characters.

Returns

  • tool"meta4"required
  • countrystringrequired
  • rowsobject[]required
    7 fields
    • group"leave" | "items" | "time" | "pay" | "leaving" | "contract"required
    • keystringrequired
    • labelstringrequired
    • unit"days" | "hours" | "amount"required
    • codestring | nullrequired

      The code sent to the payroll tool (null: none yet).

    • status"confirmed" | "to_confirm" | "missing"required

      confirmed: HR set or confirmed it; to_confirm: Bizisy's starter code, a placeholder; missing: no code (rows of this kind are listed as problems in the export).

    • descriptionstring | nullrequired

      The tool's description of the code, from a pasted code list.

  • countsobjectrequired
    3 fields
    • confirmedintegerrequired
    • to_confirmintegerrequired
    • missingintegerrequired
  • updated_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/code_map.set \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "rows": [
    {
      "group": "leave",
      "key": "vacation",
      "code": "F01",
      "description": "Férias"
    },
    {
      "group": "pay",
      "key": "base",
      "code": null
    }
  ]
}'
Response
{
  "data": {
    "tool": "meta4",
    "country": "PT",
    "updated_at": "2026-11-14T10:00:00.000Z",
    "counts": {
      "confirmed": 1,
      "to_confirm": 1,
      "missing": 1
    },
    "rows": [
      {
        "group": "leave",
        "key": "vacation",
        "label": "Holidays",
        "unit": "days",
        "code": "F01",
        "status": "confirmed",
        "description": "Férias"
      },
      {
        "group": "items",
        "key": "c1",
        "label": "Bonus",
        "unit": "amount",
        "code": null,
        "status": "missing",
        "description": null
      },
      {
        "group": "pay",
        "key": "base",
        "label": "Base pay",
        "unit": "amount",
        "code": "VB",
        "status": "to_confirm",
        "description": null
      }
    ]
  }
}

Match a Meta4 code list#

POST/v1/payroll/code_map.matchRead

Reads a code list pasted from Meta4 (its concept and absence tables: one code and description per line, separated by a tab, semicolon or comma) and proposes the code of each row of the code map whose description names it (Portuguese, Spanish or English words; the company's own leave types and pay items by their name). Nothing is saved: send the proposals you accept to payroll_code_map_set. Returns the proposals, the rows left to fill by hand, and the lines no row matched. At most 200 kB of text. 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_code_map_match on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • tool"meta4"

    Default "meta4".

  • textstringrequired

    1–200000 characters.

Returns

  • linesintegerrequired

    Code lines read from the text.

  • matchesobject[]required
    6 fields
    • group"leave" | "items" | "time" | "pay" | "leaving" | "contract"required
    • keystringrequired
    • labelstringrequired
    • codestringrequired
    • descriptionstringrequired
    • changedbooleanrequired

      Differs from the code the row has now.

  • openobject[]required

    Rows no line named: fill them by hand.

    3 fields
    • group"leave" | "items" | "time" | "pay" | "leaving" | "contract"required
    • keystringrequired
    • labelstringrequired
  • unusedobject[]required

    Lines that named no row (codes Bizisy does not send, such as taxes).

    Up to 200 items.

    2 fields
    • codestringrequired
    • descriptionstringrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/code_map.match \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"F01;Férias\nVB01;Vencimento base"}'
Response
{
  "data": {
    "lines": 2,
    "matches": [
      {
        "group": "leave",
        "key": "vacation",
        "label": "Holidays",
        "code": "F01",
        "description": "Férias",
        "changed": false
      },
      {
        "group": "pay",
        "key": "base",
        "label": "Base pay",
        "code": "VB01",
        "description": "Vencimento base",
        "changed": true
      }
    ],
    "open": [
      {
        "group": "items",
        "key": "c1",
        "label": "Bonus"
      }
    ],
    "unused": []
  }
}

Reconcile a period with Meta4#

POST/v1/payroll/reconcile.runWrite

Compares what Meta4 paid for a locked period (rows from its results file: employee_number or person_id, the concept code, units and/or amount) with what the period's last Meta4 export sent, per person and code: matched, different (both values), not_in_meta4 (sent, not paid: not loaded, wrong code, person not found) or only_in_meta4 (a code Bizisy manages paid without being sent: a change made in Meta4). Codes Bizisy doesn't send (taxes, social security) are counted as ignored. Replaces the period's previous reconciliation; dry_run compares without keeping it. At most 200,000 rows. Owners, admins, HR and roles with Payroll at Edit that cover everyone in the period; API keys and AI apps need a pay 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
MCP tool
payroll_reconcile_run 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
Body limit
20 MiB (other actions: 2 MiB)

Input

  • period_idstringrequired

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

    12–120 characters.

  • rowsobject[]required

    1–200000 items.

    5 fields
    • employee_numberstring

      1–20 characters.

    • person_idstring

      1–64 characters.

    • codestringrequired

      1–40 characters.

    • unitsnumber | null

      From -10000000 to 10000000.

    • amountnumber | null

      From -1000000000 to 1000000000.

Returns

  • period_idstringrequired
  • export_idstringrequired
  • created_atstringrequired
  • countsobjectrequired
    6 fields
    • matchedintegerrequired
    • differentintegerrequired
    • not_in_meta4integerrequired
    • only_in_meta4integerrequired
    • ignoredintegerrequired

      Lines of codes Bizisy doesn't send (taxes, social security…).

    • unknownintegerrequired

      Lines whose employee number is nobody in the period.

  • rowsobject[]required

    The lines not matched (different first), at most 3000; matched lines are counted.

    9 fields
    • person_idstringrequired
    • namestringrequired
    • employee_numberstring | nullrequired
    • codestringrequired
    • state"matched" | "different" | "not_in_meta4" | "only_in_meta4"required
    • sent_unitsnumber | nullrequired
    • sent_amountnumber | nullrequired
    • paid_unitsnumber | nullrequired
    • paid_amountnumber | nullrequired
  • truncatedbooleanrequired

    More lines were not matched than are kept.

Errors

validation_failed unauthenticated forbidden not_found conflict payload_too_large rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/reconcile.run \
  -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",
      "code": "SR",
      "units": 21,
      "amount": 158.97
    },
    {
      "person_id": "p2",
      "code": "HE1",
      "units": 4
    }
  ]
}'
Response
{
  "data": {
    "period_id": "e1:2026-03-01",
    "export_id": "x1",
    "created_at": "2026-04-03T10:00:00.000Z",
    "counts": {
      "matched": 12,
      "different": 1,
      "not_in_meta4": 1,
      "only_in_meta4": 0,
      "ignored": 212,
      "unknown": 0
    },
    "truncated": false,
    "rows": [
      {
        "person_id": "p2",
        "name": "Bruno Costa",
        "employee_number": "1002",
        "code": "HE1",
        "state": "different",
        "sent_units": 6.5,
        "sent_amount": null,
        "paid_units": 6,
        "paid_amount": 41.2
      }
    ]
  }
}

Get a period's reconciliation with Meta4#

POST/v1/payroll/reconcile.getRead

The last reconciliation of a locked period with Meta4 (payroll_reconcile_run): counts and the rows, differences first, with each person's name and employee number. null when the period hasn't been reconciled. Owners, admins, HR and roles with Payroll at Edit that cover everyone in the period; API keys and AI apps need a pay 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); this read of stored data keeps working while it is off.

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

  • period_idstringrequired
  • export_idstringrequired
  • created_atstringrequired
  • countsobjectrequired
    6 fields
    • matchedintegerrequired
    • differentintegerrequired
    • not_in_meta4integerrequired
    • only_in_meta4integerrequired
    • ignoredintegerrequired

      Lines of codes Bizisy doesn't send (taxes, social security…).

    • unknownintegerrequired

      Lines whose employee number is nobody in the period.

  • rowsobject[]required

    The lines not matched (different first), at most 3000; matched lines are counted.

    9 fields
    • person_idstringrequired
    • namestringrequired
    • employee_numberstring | nullrequired
    • codestringrequired
    • state"matched" | "different" | "not_in_meta4" | "only_in_meta4"required
    • sent_unitsnumber | nullrequired
    • sent_amountnumber | nullrequired
    • paid_unitsnumber | nullrequired
    • paid_amountnumber | nullrequired
  • truncatedbooleanrequired

    More lines were not matched than are kept.

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/payroll/reconcile.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",
    "export_id": "x1",
    "created_at": "2026-04-03T10:00:00.000Z",
    "counts": {
      "matched": 12,
      "different": 1,
      "not_in_meta4": 1,
      "only_in_meta4": 0,
      "ignored": 212,
      "unknown": 0
    },
    "truncated": false,
    "rows": [
      {
        "person_id": "p2",
        "name": "Bruno Costa",
        "employee_number": "1002",
        "code": "HE1",
        "state": "different",
        "sent_units": 6.5,
        "sent_amount": null,
        "paid_units": 6,
        "paid_amount": 41.2
      }
    ]
  }
}

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

Developer docs