Skip to content

API reference

Country obligations

What each legal entity's country asks of an employer: obligations and deadlines, hire and leave notices (preparing, sending to Segurança Social, recording), country data, Segurança Social access and the Relatório Único file. Preparing, sending, the file and credentials happen in the web app.

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

List country obligations#

POST/v1/country/obligations.listRead

For each legal entity: the rules of its country (Portugal, Spain and France have their own; other EU and EEA countries follow the EU minimum, Directive (EU) 2019/1152; elsewhere Bizisy has none yet), each obligation (hire and leave notices, yearly staff reports, written terms) with its authority, law and official source, its deadline, how Bizisy helps (send: Bizisy sends it to the authority; manual: Bizisy prepares it and HR records it; file: Bizisy makes the official file; sheet: a data sheet for whoever files it), how many need someone now, and how many country data values are missing. segsocial says whether sending to Segurança Social is switched on for this server. Owners, admins and HR.

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

Input

No input: send {}.

Returns

  • entitiesobject[]required
    5 fields
    • legal_entityobjectrequired
      4 fields
      • idstringrequired
      • namestringrequired
      • countrystringrequired
      • archivedbooleanrequired
    • rulesobject | nullrequired

      null: Bizisy has no rules for this country (outside the EU and EEA).

      4 fields
      • countrystring | nullrequired

        The country whose own rules apply; null: the EU default.

      • sourcestringrequired
      • checked_onstringrequired
      • notestring | nullrequired
    • obligationsobject[]required
      12 fields
      • idstringrequired
      • kindstring (enum)required

        One of: hire_notice, leave_notice, staff_report, written_terms, vacation_plan, pay_notice, payroll_declaration, training_hours, schedule_map.

      • authoritystringrequired
      • lawstringrequired
      • source_urlstringrequired
      • deadlineobjectrequired
        8 fields
        • kindstringrequired
        • daysinteger
        • opens_daysinteger
        • dayinteger
        • fromstring
        • tostring
        • bystring
        • untilstring
      • channel"webservice" | "file" | "sheet" | "info" | "post"required

        webservice: Bizisy can send it to the authority; file: Bizisy makes the official file; sheet: Bizisy prepares the data for whoever files it; post: Bizisy makes a printable document a person posts at the workplace; info: nothing to file per person.

      • how"send" | "manual" | "file" | "sheet" | "info" | "post"required

        How it works for this company now: send (Bizisy sends it), manual (Bizisy prepares it, you make it in the authority's portal and record it), file, sheet or info.

      • openintegerrequired

        Notices or reports of this obligation that need someone now (due, overdue or refused).

      • notestring | nullrequired
      • annexesobject[]required

        Yearly reports with annexes: what Bizisy fills of each (full, partial, out) and why.

        4 fields
        • idstringrequired
        • namestringrequired
        • scope"full" | "partial" | "out"required
        • whystringrequired
      • fromstring | nullrequired

        The rule applies to events from this day (e.g. Portugal's pay-change notices from 2027).

    • missingintegerrequired

      Country data values these obligations need that are not entered yet (company data: legal entity, locations, job titles).

    • payrollstring[]required

      Payroll exports or connectors that fit this country (ids).

  • segsocialobjectrequired
    2 fields
    • availablebooleanrequired
    • environment"production" | "quality"required

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/country/obligations.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "entities": [
      {
        "legal_entity": {
          "id": "le1",
          "name": "Acme Portugal Lda",
          "country": "PT",
          "archived": false
        },
        "rules": {
          "country": "PT",
          "source": "pt-2026-10",
          "checked_on": "2026-10-10",
          "note": null
        },
        "obligations": [
          {
            "annexes": [],
            "from": null,
            "id": "pt.hire",
            "kind": "hire_notice",
            "authority": "Segurança Social",
            "law": "Código dos Regimes Contributivos, art. 29.º (Lei 24-D/2022)",
            "source_url": "https://diariodarepublica.pt/dr/detalhe/lei/110-2009-490249",
            "deadline": {
              "kind": "before_start",
              "days": 15
            },
            "channel": "webservice",
            "how": "send",
            "open": 1,
            "note": null
          }
        ],
        "missing": 2,
        "payroll": []
      }
    ],
    "segsocial": {
      "available": true,
      "environment": "production"
    }
  }
}

List hire and leave notices#

POST/v1/country/notices.listRead

Statutory notices for people joining or leaving a legal entity whose country asks for one (Portugal: Segurança Social hire and leave notices; Spain: Social Security alta and baja, Contrat@; France: DPAE), and yearly reports (Portugal: Relatório Único). Each has its deadline (opens_on, due_on) and state: upcoming, due, overdue, failed (the authority refused it: record.error says why), sent or skipped (not needed). Listed: events from 90 days ago to 60 days ahead, plus everything already recorded. Names and dates only; the data each carries is in Bizisy (prepare). Pay change notices (Portugal, from 2027) are listed in the app only: over an API key or AI connection they are left out. open: only due, overdue and failed. Owners, admins and HR.

Who can call it
Manage key owner admin hr
Keys and apps
Pay change notices (they reveal a pay change) are left out.
MCP tool
country_notices_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • openboolean

    Only those that need someone now (due, overdue, failed).

  • person_idstring

    1–100 characters.

  • legal_entity_idstring

    1–100 characters.

Returns

  • as_ofstringrequired
  • noticesobject[]required
    15 fields
    • keystringrequired

      Stable notice key (obligation:subject:date) for country_notices_record and the app.

    • obligationstringrequired
    • countrystringrequired
    • kindstring (enum)required

      One of: hire_notice, leave_notice, staff_report, written_terms, vacation_plan, pay_notice, payroll_declaration, training_hours, schedule_map.

    • channel"webservice" | "file" | "sheet" | "info" | "post"required
    • authoritystringrequired
    • personobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • legal_entityobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • event"hire" | "leave" | "report" | "pay"required
    • event_datestringrequired

      The first day (hire), the last day (leave), the day base pay changed (pay; listed in the app only) or the year (report).

    • opens_onstringrequired

      From when it can be made.

    • due_onstringrequired

      Its last day.

    • state"upcoming" | "due" | "overdue" | "failed" | "sent" | "skipped"required

      upcoming (not yet), due, overdue, failed (the authority refused it), sent, skipped (not needed).

    • currentbooleanrequired

      False for a record about a date Bizisy no longer has (the start or last day was corrected).

    • recordobject | nullrequired
      7 fields
      • status"sent" | "failed" | "skipped"required
      • channel"webservice" | "manual"required
      • referencestring | nullrequired
      • sent_onstring | nullrequired
      • reasonstring | nullrequired
      • errorobject | nullrequired
        3 fields
        • code"refused" | "auth" | "unavailable" | "invalid"required
        • messagestringrequired
        • officialstring | nullrequired

          The authority's own message, only when it is one of its documented ones.

      • attemptsintegerrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/country/notices.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"person_id":"p1","legal_entity_id":"le1"}'
Response
{
  "data": {
    "as_of": "2026-10-10",
    "notices": [
      {
        "key": "pt.hire:p1:2026-10-20",
        "obligation": "pt.hire",
        "country": "PT",
        "kind": "hire_notice",
        "channel": "webservice",
        "authority": "Segurança Social",
        "person": {
          "id": "p1",
          "name": "Beatriz Lopes"
        },
        "legal_entity": {
          "id": "le1",
          "name": "Acme Portugal Lda"
        },
        "event": "hire",
        "event_date": "2026-10-20",
        "opens_on": "2026-10-05",
        "due_on": "2026-10-19",
        "state": "due",
        "current": true,
        "record": null
      },
      {
        "key": "pt.leave:p2:2026-09-30",
        "obligation": "pt.leave",
        "country": "PT",
        "kind": "leave_notice",
        "channel": "webservice",
        "authority": "Segurança Social",
        "person": {
          "id": "p2",
          "name": "Rui Costa"
        },
        "legal_entity": {
          "id": "le1",
          "name": "Acme Portugal Lda"
        },
        "event": "leave",
        "event_date": "2026-09-30",
        "opens_on": "2026-09-30",
        "due_on": "2026-10-10",
        "state": "failed",
        "current": true,
        "record": {
          "status": "failed",
          "channel": "webservice",
          "reference": null,
          "sent_on": null,
          "reason": null,
          "error": {
            "code": "refused",
            "message": "Choose the reason the employment ended.",
            "official": "Motivo fim vínculo não identificado"
          },
          "attempts": 1
        }
      }
    ]
  }
}

Prepare a notice#

POST/v1/country/notices.prepareRead

Everything one notice carries, from Bizisy's data and the country data: for Portugal the exact Segurança Social payload (or, when sending is off, the values to type in Segurança Social Direta); for Spain the Contrat@ XML file (permanent full-time contracts) or a data sheet; for France the DPAE data sheet. missing lists what to fill in first (a person's NISS, a job title's profession code, a choice such as the reason for a fixed-term contract). It holds private and pay data: in the app only.

Web app only
Refused for API keys and connected apps. A notice's data (NISS, date of birth, pay) is private: it is prepared in the app.
MCP tool
country_notices_prepare on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • keystringrequired

    5–160 characters.

  • choicesobject
    8 fields
    • modalidadestring (enum)

      PT hire: contract type (modalidade de contrato), default from the job's contract type and FTE.

      One of: A, C, AA, AB, S, B, D, BA, BB, R, E, EA, EB, O, F, FA, FB, N, G, GA, GB, Q, H, HA, HB, P, I.

    • prestacao"P" | "T" | "A"

      PT hire: P on site, T fully remote, A partly remote; default from the location.

    • motivo_contratostring (enum)

      PT hire: the reason for a fixed or open-dated term contract (required for those).

      One of: AEAT, ATSA, CTSD, EOPA, ESTA, EXTO, IFEE, LNAT, NIMO, NIPA, RAPT, STAJ, STAT, STLR, STPS, STTC, STTT, S2MT, VAPT, OMAP, OMCS, OMEL, OSIN.

    • remuneracao_basenumber

      PT hire: monthly base pay in euros, when Bizisy's pay is not monthly.

      From 0 to 1000000000.

    • motivo_fimstring (enum)

      PT leave: the reason the employment ended (required).

      One of: CCAI, CCCT, CCEE, CCFM, CCMT, CCRI, CCRV, CDT, IECC, IEDC, IEEX, IEIN, IEJC, IEPE, IIAT, IIDD, IIDE, IIJC, IISA, MAPC, RADC, RANE, RAOT, RARC, RARD, RARE, RARR, RETR, TE.

    • comunicacao_desemprego0 | 1

      PT leave: reported for unemployment benefit (default 1; Segurança Social records it either way).

    • fundamentacaostring

      PT leave: justification, required for RARC, RARD, RARE and RARR with unemployment 1.

      Up to 500 characters.

    • enquadramentostring (enum)

      One of: IPSS, PEIN, PEVE, PFPI, PFPV, REGE, RGTC, RGTL, RGTS, TCCD, TFPC, TFPM, TFPN, TRAG, TRCD.

Returns

8 fields
  • noticeobjectrequired
    15 fields
    • keystringrequired

      Stable notice key (obligation:subject:date) for country_notices_record and the app.

    • obligationstringrequired
    • countrystringrequired
    • kindstring (enum)required

      One of: hire_notice, leave_notice, staff_report, written_terms, vacation_plan, pay_notice, payroll_declaration, training_hours, schedule_map.

    • channel"webservice" | "file" | "sheet" | "info" | "post"required
    • authoritystringrequired
    • personobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • legal_entityobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • event"hire" | "leave" | "report" | "pay"required
    • event_datestringrequired

      The first day (hire), the last day (leave), the day base pay changed (pay; listed in the app only) or the year (report).

    • opens_onstringrequired

      From when it can be made.

    • due_onstringrequired

      Its last day.

    • state"upcoming" | "due" | "overdue" | "failed" | "sent" | "skipped"required

      upcoming (not yet), due, overdue, failed (the authority refused it), sent, skipped (not needed).

    • currentbooleanrequired

      False for a record about a date Bizisy no longer has (the start or last day was corrected).

    • recordobject | nullrequired
      7 fields
      • status"sent" | "failed" | "skipped"required
      • channel"webservice" | "manual"required
      • referencestring | nullrequired
      • sent_onstring | nullrequired
      • reasonstring | nullrequired
      • errorobject | nullrequired
        3 fields
        • code"refused" | "auth" | "unavailable" | "invalid"required
        • messagestringrequired
        • officialstring | nullrequired

          The authority's own message, only when it is one of its documented ones.

      • attemptsintegerrequired
  • how"send" | "manual" | "file" | "sheet" | "info" | "post"required
  • missingobject[]required
    3 fields
    • keystringrequired
    • subjectstring (enum)required

      One of: person, job, pay, entity, location, title, choice.

    • subject_idstring | nullrequired
  • warningsstring[]required
  • payloadobject | nullrequired
  • choicesobjectrequired
  • sheetobject[]required
    2 fields
    • keystringrequired
    • valuestring | nullrequired
  • fileobject | nullrequired
    3 fields
    • filenamestringrequired
    • content_base64stringrequired
    • content_typestringrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/country/notices.prepare \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "pt.leave:p1:2026-09-30",
  "choices": {
    "motivo_fim": "IIDD",
    "comunicacao_desemprego": 1
  }
}'
Response
{
  "data": {
    "notice": {
      "key": "pt.hire:p1:2026-10-20",
      "obligation": "pt.hire",
      "country": "PT",
      "kind": "hire_notice",
      "channel": "webservice",
      "authority": "Segurança Social",
      "person": {
        "id": "p1",
        "name": "Beatriz Lopes"
      },
      "legal_entity": {
        "id": "le1",
        "name": "Acme Portugal Lda"
      },
      "event": "hire",
      "event_date": "2026-10-20",
      "opens_on": "2026-10-05",
      "due_on": "2026-10-19",
      "state": "due",
      "current": true,
      "record": null
    },
    "how": "send",
    "missing": [
      {
        "key": "pt_cpp",
        "subject": "title",
        "subject_id": "t1"
      }
    ],
    "warnings": [
      "pay_from_year"
    ],
    "payload": null,
    "choices": {
      "modalidade": "A",
      "prestacao": "P",
      "remuneracao_base": 1500
    },
    "sheet": [
      {
        "key": "worker_niss",
        "value": "12345678901"
      },
      {
        "key": "pt_cpp",
        "value": null
      }
    ],
    "file": null
  }
}

Send a notice to Segurança Social#

POST/v1/country/notices.submitWrite

Portugal: sends a hire notice (from 15 days before the start), a leave notice (once the last day has passed) or, from 2027, a change of base pay (once its day has come: every monthly base pay since the start, as Comunicar Remunerações Permanentes wants) to Segurança Social with the legal entity's credentials, after HR reviewed it; a dry run returns the exact payload without sending. Segurança Social gives no reference number: Bizisy records when and by whom it was sent. When it refuses, the notice is failed with Segurança Social's reason in Bizisy's words (error) and can be sent again after the fix. Only when sending to Segurança Social is on and an owner or admin entered the credentials; otherwise make it in Segurança Social Direta and record it with country_notices_record. In the app only.

Web app only
Refused for API keys and connected apps. HR reviews and sends a notice to Segurança Social in the app.
MCP tool
country_notices_submit 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

  • keystringrequired

    5–160 characters.

  • choicesobject
    8 fields
    • modalidadestring (enum)

      PT hire: contract type (modalidade de contrato), default from the job's contract type and FTE.

      One of: A, C, AA, AB, S, B, D, BA, BB, R, E, EA, EB, O, F, FA, FB, N, G, GA, GB, Q, H, HA, HB, P, I.

    • prestacao"P" | "T" | "A"

      PT hire: P on site, T fully remote, A partly remote; default from the location.

    • motivo_contratostring (enum)

      PT hire: the reason for a fixed or open-dated term contract (required for those).

      One of: AEAT, ATSA, CTSD, EOPA, ESTA, EXTO, IFEE, LNAT, NIMO, NIPA, RAPT, STAJ, STAT, STLR, STPS, STTC, STTT, S2MT, VAPT, OMAP, OMCS, OMEL, OSIN.

    • remuneracao_basenumber

      PT hire: monthly base pay in euros, when Bizisy's pay is not monthly.

      From 0 to 1000000000.

    • motivo_fimstring (enum)

      PT leave: the reason the employment ended (required).

      One of: CCAI, CCCT, CCEE, CCFM, CCMT, CCRI, CCRV, CDT, IECC, IEDC, IEEX, IEIN, IEJC, IEPE, IIAT, IIDD, IIDE, IIJC, IISA, MAPC, RADC, RANE, RAOT, RARC, RARD, RARE, RARR, RETR, TE.

    • comunicacao_desemprego0 | 1

      PT leave: reported for unemployment benefit (default 1; Segurança Social records it either way).

    • fundamentacaostring

      PT leave: justification, required for RARC, RARD, RARE and RARR with unemployment 1.

      Up to 500 characters.

    • enquadramentostring (enum)

      One of: IPSS, PEIN, PEVE, PFPI, PFPV, REGE, RGTC, RGTL, RGTS, TCCD, TFPC, TFPM, TFPN, TRAG, TRCD.

Returns

  • status"preview" | "sent" | "failed"required
  • payloadobjectrequired
  • errorobject | nullrequired
    3 fields
    • code"refused" | "auth" | "unavailable" | "invalid"required
    • messagestringrequired
    • officialstring | nullrequired

      The authority's own message, only when it is one of its documented ones.

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/country/notices.submit \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "key": "pt.hire:p1:2026-10-20",
  "choices": {
    "modalidade": "E",
    "motivo_contrato": "ATSA",
    "prestacao": "P"
  }
}'
Response
{
  "data": {
    "status": "sent",
    "payload": {
      "niss-trabalhador": 12345678901,
      "inicio-contrato": "2026-10-20"
    },
    "error": null
  }
}

Record notices as sent or not needed#

POST/v1/country/notices.recordWrite

Records up to 200 notices (keys from country_notices_list) as sent — made outside Bizisy, with an optional receipt number and the day — or as skipped, not needed (already_done, not_employment, handled_by_provider, duplicate, other). A notice already sent through Bizisy can't be recorded again (reopen it first). Owners, admins and HR.

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

Input

  • itemsobject[]required

    1–200 items.

    5 fields
    • keystringrequired

      5–160 characters.

    • status"sent" | "skipped"required

      sent: it was made (outside Bizisy, e.g. in Segurança Social Direta or by your gestoría); skipped: not needed.

    • referencestring

      sent: the receipt number, when there is one.

      Up to 60 characters. Pattern ^[\w ./-]*$.

    • sent_onstring

      sent: the day it was made (default today).

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

    • reason"already_done" | "not_employment" | "handled_by_provider" | "duplicate" | "other"

      skipped: why it is not needed.

Returns

  • recordedintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/country/notices.record \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "items": [
    {
      "key": "pt.hire:p1:2026-10-20",
      "status": "sent",
      "reference": "SSD-123",
      "sent_on": "2026-10-12"
    },
    {
      "key": "es.alta:p2:2026-10-01",
      "status": "skipped",
      "reason": "handled_by_provider"
    }
  ]
}'
Response
{
  "data": {
    "recorded": 2
  }
}

Reopen a notice#

POST/v1/country/notices.reopenWrite

Removes what was recorded about a notice (sent, failed or not needed), so it is due again — for a notice recorded by mistake, or one that must be sent again after a correction. It changes nothing at the authority. Owners, admins and HR.

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

Input

  • keystringrequired

    5–160 characters.

Returns

  • reopenedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/country/notices.reopen \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"key":"pt.hire:p1:2026-10-20"}'
Response
{
  "data": {
    "reopened": true
  }
}

Get country data#

POST/v1/country/facts.getRead

The codes country obligations need that Bizisy does not hold, and where they are missing: per legal entity (e.g. Portugal: employer NISS, CAE, Relatório Único entity number; Spain: CCC; France: SIRET), per location (workplace and establishment numbers), per job title (Portugal: CPP profession code, qualification level, category; Spain: CNO-11) and per person (nationality, education level, place of birth: private, so never over an API key or AI connection). fields lists every field with its pattern and the official table to take it from. Owners, admins and HR.

Who can call it
Manage key owner admin hr
Keys and apps
Person country data is left out.
MCP tool
country_facts_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • subject"entity" | "location" | "title" | "person"

Returns

  • fieldsobject[]required
    8 fields
    • keystringrequired
    • subject"entity" | "location" | "title" | "person"required
    • labelstringrequired
    • helpstringrequired
    • patternstringrequired
    • tier"company" | "private"required
    • defaultstring | nullrequired
    • countriesstring[]required
  • subjectsobject[]required
    8 fields
    • subject"entity" | "location" | "title" | "person"required
    • idstringrequired
    • namestringrequired
    • countrystring | nullrequired
    • valuesobjectrequired
    • fieldsstring[]required

      The keys this subject takes (from its countries' rules).

    • missingstring[]required

      Keys with no value and no default.

    • suggestionsobject[]required

      People only: a code their talent profile's completed degree suggests (spec 2026-11-21-internal-talent T1), when the value differs. Never set by itself: HR sets it with country_facts_set.

      3 fields
      • keystringrequired
      • codestringrequired
      • fromobjectrequired
        3 fields
        • qualificationstringrequired
        • isced_levelintegerrequired
        • isced_fieldstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/country/facts.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"subject":"title"}'
Response
{
  "data": {
    "fields": [
      {
        "key": "pt_cpp",
        "subject": "title",
        "label": "Profession code (CPP 2010)",
        "help": "The 5-digit code of the Classificação Portuguesa das Profissões 2010.",
        "pattern": "^\\d{5}
quot;
, "tier": "company", "default": null, "countries": [ "PT" ] } ], "subjects": [ { "subject": "title", "id": "t1", "name": "Engineer", "country": null, "values": {}, "fields": [ "pt_cpp" ], "missing": [ "pt_cpp" ], "suggestions": [] }, { "subject": "person", "id": "p1", "name": "Rita Silva", "country": null, "values": {}, "fields": [ "pt_habil_lit" ], "missing": [ "pt_habil_lit" ], "suggestions": [ { "key": "pt_habil_lit", "code": "634", "from": { "qualification": "Licenciatura em Gestão", "isced_level": 6, "isced_field": "0413" } } ] } ] } }

Set country data#

POST/v1/country/facts.setWrite

Sets or clears (null) country data values on one subject: a legal entity, location, job title or person (subject_id from country_facts_get). Each value must match its field's pattern (e.g. a 5-digit CPP code). Person values are private: in the app only. Owners, admins and HR.

Who can call it
Manage key owner admin hr
Keys and apps
Person country data (nationality, education level, place of birth) is refused; company codes are allowed.
MCP tool
country_facts_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

  • subject"entity" | "location" | "title" | "person"required
  • subject_idstringrequired

    1–100 characters.

  • valuesobjectrequired

Returns

  • valuesobjectrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/country/facts.set \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "subject": "title",
  "subject_id": "t1",
  "values": {
    "pt_cpp": "25121",
    "pt_nivel_qual": null
  }
}'
Response
{
  "data": {
    "values": {
      "pt_cpp": "25121"
    }
  }
}

List Segurança Social credentials#

POST/v1/country/credentials.listRead

For each Portuguese legal entity: whether Segurança Social credentials are set (the NISS or sub-account user, never the password), and their state: unchecked (not used yet), working (the last notice went through) or refused (Segurança Social refused them: an owner or admin enters them again). available says whether sending to Segurança Social is switched on for this server. Owners, admins and HR.

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

Input

No input: send {}.

Returns

  • availablebooleanrequired
  • environment"production" | "quality"required
  • entitiesobject[]required
    2 fields
    • legal_entityobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • credentialsobject | nullrequired
      4 fields
      • usernamestringrequired
      • status"unchecked" | "working" | "refused"required
      • checked_atstring | nullrequired
      • set_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/country/credentials.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "available": true,
    "environment": "production",
    "entities": [
      {
        "legal_entity": {
          "id": "le1",
          "name": "Acme Portugal Lda"
        },
        "credentials": {
          "username": "20000000001",
          "status": "working",
          "checked_at": "2026-10-09T10:00:00.000Z",
          "set_at": "2026-10-01T09:00:00.000Z"
        }
      }
    ]
  }
}

Set Segurança Social credentials#

POST/v1/country/credentials.setWrite

Enters the Segurança Social Direta user (the legal entity's NISS, or a sub-account) and its password — or an application password once two-factor login is on — for one Portuguese legal entity. Bizisy keeps the password encrypted and never shows it again; it is checked the first time a notice is sent. Replaces any credentials before. Owners and admins, in the app only.

Web app only
Refused for API keys and connected apps. Segurança Social access is entered by an owner or admin in the app.
MCP tool
country_credentials_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

  • legal_entity_idstringrequired

    1–100 characters.

  • usernamestringrequired

    3–40 characters. Pattern ^[\w.@-]+$.

  • passwordstringrequired

    1–200 characters.

Returns

  • legal_entity_idstringrequired
  • usernamestringrequired
  • status"unchecked"required

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/country/credentials.set \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "legal_entity_id": "le1",
  "username": "20000000001",
  "password": "app-password"
}'
Response
{
  "data": {
    "legal_entity_id": "le1",
    "username": "20000000001",
    "status": "unchecked"
  }
}

Remove Segurança Social credentials#

POST/v1/country/credentials.clearDestructive

Removes the Segurança Social credentials of one Portuguese legal entity: Bizisy can no longer send its notices (they can still be prepared and recorded). Owners and admins, in the app only.

Web app only
Refused for API keys and connected apps. Segurança Social access is removed in the app.
MCP tool
country_credentials_clear 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

    1–100 characters.

Returns

  • removedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/country/credentials.clear \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"legal_entity_id":"le1"}'
Response
{
  "data": {
    "removed": true
  }
}

Check the Relatório Único#

POST/v1/country/relatorio_unico.readinessRead

Portugal: for each Portuguese legal entity with people in the year, how ready its Relatório Único is — the year being prepared (last year until October's report is made; from November, this year), the legal window (16 March – 15 April of the next year, moved by notice in recent years), state (preparing, due, overdue, sent, skipped), how many people are in Anexo A (October) and Anexo B (joined or left), and what is missing grouped by key with the records to fix (e.g. pt_cpp on job titles, social_security_number on people, pt_ru_motivo_saida on leavers; with the Training module on, Anexo C's gaps: pt_area on training courses, NISS of everyone employed in the year). The records to fix are named in the app only; over an API key or AI connection only their counts are given. history lists the files made (who, when, which annexes). Owners, admins, HR and roles with Payroll at View (an accounting firm's Accountant role).

Who can call it
Manage key owner admin hr
Keys and apps
The records to fix come with their ids only, never names.
MCP tool
country_relatorio_unico_readiness on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • yearinteger

    From 2010 to 2100.

  • legal_entity_idstring

    1–100 characters.

Returns

  • as_ofstringrequired
  • yearintegerrequired
  • entitiesobject[]required
    13 fields
    • legal_entityobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • yearintegerrequired
    • opens_onstringrequired

      The legal window (Portaria 55/2010 art. 4.º: 16 March); it has been moved by notice in recent years.

    • due_onstringrequired
    • state"preparing" | "due" | "overdue" | "sent" | "skipped"required
    • readybooleanrequired

      Nothing required is missing for Anexos A and B (the gaps of Anexos 0, C, D and F are listed in missing with their annex).

    • workersintegerrequired

      People in Anexo A (employed at some point in October).

    • movementsintegerrequired

      People in Anexo B (started and/or left in the year).

    • missing_totalintegerrequired
    • missingobject[]required
      5 fields
      • keystringrequired

        What is missing: a country data key (pt_cpp, pt_ru_motivo_saida…), a Bizisy field (social_security_number, sex, birthday), for Anexo C a training course's area (pt_area on a course or a one-off training record), or, with subject report, a yearly form's answer (Anexo 0: ru0_form, ru0_turnover, ru0_union_members, ru0_overtime, ru0_overtime_list, ru0_temp_average; Anexo D: ru_d_form, ru_d_organisation, ru_d_safety_modes, ru_d_health_modes, ru_d_together, ru_d_employer, ru_d_designated, ru_d_accidents; Anexo F: ru_f_providers, ru_f_provider) — fill them with country_relatorio_unico_annual_set and country_relatorio_unico_providers_save in the app.

      • subjectstring (enum)required

        One of: person, job, pay, entity, location, title, choice, course, training_record, report.

      • annexes"0" | "A" | "B" | "C" | "D" | "F"[]required
      • countintegerrequired
      • itemsobject[]required

        The records to fix, with names; empty over API keys and AI connections (counts only).

        2 fields
        • idstring | nullrequired
        • namestring | nullrequired
    • warningsstring[]required
    • historyobject[]required
      8 fields
      • idstringrequired
      • yearintegerrequired
      • annexesstring (enum)[]required

        One of: 0, A, B, C, D, E, F.

      • workersintegerrequired
      • movementsintegerrequired
      • missingintegerrequired
      • by_firmstring | nullrequired
      • created_atstringrequired
    • sentobject | nullrequired
      2 fields
      • sent_onstring | nullrequired
      • referencestring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/country/relatorio_unico.readiness \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":2025,"legal_entity_id":"le1"}'
Response
{
  "data": {
    "as_of": "2026-03-20",
    "year": 2025,
    "entities": [
      {
        "legal_entity": {
          "id": "le1",
          "name": "Acme Portugal Lda"
        },
        "year": 2025,
        "opens_on": "2026-03-16",
        "due_on": "2026-04-15",
        "state": "due",
        "ready": false,
        "workers": 12,
        "movements": 6,
        "missing_total": 6,
        "missing": [
          {
            "key": "pt_cpp",
            "subject": "title",
            "annexes": [
              "A",
              "B"
            ],
            "count": 2,
            "items": [
              {
                "id": "t1",
                "name": "Engineer"
              },
              {
                "id": "t2",
                "name": "Office manager"
              }
            ]
          },
          {
            "key": "social_security_number",
            "subject": "person",
            "annexes": [
              "A"
            ],
            "count": 1,
            "items": [
              {
                "id": "p3",
                "name": "Rui Costa"
              }
            ]
          },
          {
            "key": "pt_ru_motivo_saida",
            "subject": "person",
            "annexes": [
              "B"
            ],
            "count": 2,
            "items": [
              {
                "id": "p7",
                "name": "Marta Lima"
              },
              {
                "id": "p8",
                "name": "João Reis"
              }
            ]
          },
          {
            "key": "pt_ru_estab",
            "subject": "location",
            "annexes": [
              "A",
              "D"
            ],
            "count": 1,
            "items": [
              {
                "id": "l2",
                "name": "Porto"
              }
            ]
          },
          {
            "key": "ru_d_form",
            "subject": "report",
            "annexes": [
              "D"
            ],
            "count": 1,
            "items": [
              {
                "id": "le1",
                "name": "Acme Portugal Lda"
              }
            ]
          }
        ],
        "warnings": [
          "ru_check_paid"
        ],
        "history": [
          {
            "id": "r1",
            "year": 2024,
            "annexes": [
              "A",
              "B"
            ],
            "workers": 10,
            "movements": 3,
            "missing": 0,
            "by_firm": "Contas & Co",
            "created_at": "2025-04-02T10:00:00.000Z"
          }
        ],
        "sent": null
      }
    ]
  }
}

Make the Relatório Único files#

POST/v1/country/relatorio_unico.generateWrite

Portugal: makes the Relatório Único files of one Portuguese legal entity for a year in the official format (DGCP RU 2025 schemas, one XML per annex): Anexo A (quadro de pessoal: everyone employed at some point in October, by establishment, with October's base pay, hours and the regular allowances of pay items mapped in Payroll), Anexo B (fluxo de entrada e saída: everyone who joined or left in the year, with the reasons), with the Training module on Anexo C (formação contínua: the training register's courses and each worker's training situation, hours brought forward or deferred and credit from their training-hour balance), with no_strikes Anexo E's "no strikes" declaration, and from the yearly forms Anexo 0 (folha de rosto: headcounts on 31 December and the yearly average, turnover, union members, posted workers, employer associations, overtime, capital, optional spending and accounts), Anexo D (health and safety at work: per establishment the average workers, hours worked, the OSH organisation and staff, and work accidents and days lost counted from time off's leave types marked as work accidents) and Anexo F (service providers). An annex's file is given only when nothing it needs is missing (missing lists what to fill first). summary is a human-readable overview (headcounts, by sex, contract, qualification, age, education, pay range, entries and exits) including Anexo 0's people figures (Anexo C is left out while the Training module is off). Upload the files in the Relatório Único platform (Launcher), then record the report as sent with country_notices_record. Each file made is kept in the history (never the file). It holds private and pay data: in the app only. Owners, admins, HR, and roles with Payroll at View that also have Private details at View.

Web app only
Refused for API keys and connected apps. The Relatório Único files hold private and pay data: they are made in the app.
MCP tool
country_relatorio_unico_generate 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

  • legal_entity_idstringrequired

    1–100 characters.

  • yearintegerrequired

    From 2010 to 2100.

  • no_strikesboolean

    You confirm there were no strikes in the year: Bizisy adds Anexo E's "no strikes" file.

Returns

9 fields
  • readybooleanrequired
  • workersintegerrequired
  • headcount_31_octoberintegerrequired
  • establishmentsintegerrequired
  • movementsintegerrequired
  • missingobject[]required
    4 fields
    • keystringrequired
    • subjectstring (enum)required

      One of: person, job, pay, entity, location, title, choice, course, training_record, report.

    • subject_idstring | nullrequired
    • annexes"0" | "A" | "B" | "C" | "D" | "F"[]required
  • warningsstring[]required
  • filesobject[]required
    4 fields
    • annexstring (enum)required

      One of: 0, A, B, C, D, E, F.

    • filenamestringrequired
    • content_base64stringrequired
    • content_typestringrequired
  • summaryobjectrequired
    19 fields
    • yearintegerrequired
    • entitystringrequired
    • headcount_31_octoberintegerrequired
    • headcount_31_decemberintegerrequired
    • average_headcountnumberrequired
    • establishmentsobject[]required
      4 fields
      • idstring | nullrequired
      • namestringrequired
      • head_officebooleanrequired
      • people_31_octoberintegerrequired
    • by_sexobjectrequired
    • by_contractobjectrequired

      By RU table 13 code.

    • by_qualificationobjectrequired

      By RU table 21 level.

    • by_ageobjectrequired
    • by_educationobjectrequired

      By the first digit of RU table 14.

    • full_timeintegerrequired
    • part_timeintegerrequired
    • payobject | nullrequired

      October monthly base pay in EUR; null with fewer than 3 people.

      3 fields
      • lowestnumberrequired
      • mediannumberrequired
      • highestnumberrequired
    • entriesintegerrequired
    • exitsintegerrequired
    • exits_by_reasonobjectrequired

      By RU table 27 code.

    • contractorsintegerrequired
    • annexesobject[]required
      2 fields
      • idstringrequired
      • status"made" | "missing_data" | "figures" | "not_asked" | "out"required

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/country/relatorio_unico.generate \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"legal_entity_id":"le1","year":2025,"no_strikes":true}'
Response
{
  "data": {
    "ready": false,
    "workers": 12,
    "headcount_31_october": 11,
    "establishments": 2,
    "movements": 6,
    "missing": [
      {
        "key": "pt_ru_motivo_saida",
        "subject": "person",
        "subject_id": "p7",
        "annexes": [
          "B"
        ]
      }
    ],
    "warnings": [
      "ru_check_paid",
      "ru_overtime_check"
    ],
    "files": [
      {
        "annex": "A",
        "filename": "relatorio-unico-2025-anexo-a-123456.xml",
        "content_type": "application/xml",
        "content_base64": "PD94bWwgdmVyc2lvbj0iMS4wIj8+PHJlbGF0b3Jpb191bmljby8+"
      }
    ],
    "summary": {
      "year": 2025,
      "entity": "Acme Portugal Lda",
      "headcount_31_october": 11,
      "headcount_31_december": 12,
      "average_headcount": 10.8,
      "establishments": [
        {
          "id": "987654",
          "name": "Lisboa",
          "head_office": true,
          "people_31_october": 8
        },
        {
          "id": "987655",
          "name": "Porto",
          "head_office": false,
          "people_31_october": 3
        }
      ],
      "by_sex": {
        "female": 6,
        "male": 5
      },
      "by_contract": {
        "10": 8,
        "20": 3
      },
      "by_qualification": {
        "2": 2,
        "4": 6,
        "5": 3
      },
      "by_age": {
        "under_25": 1,
        "25_34": 5,
        "35_44": 4,
        "45_54": 2
      },
      "by_education": {
        "3": 3,
        "6": 7,
        "7": 2
      },
      "full_time": 10,
      "part_time": 1,
      "pay": {
        "lowest": 870,
        "median": 1450,
        "highest": 3200
      },
      "entries": 4,
      "exits": 2,
      "exits_by_reason": {
        "110": 1,
        "112": 1
      },
      "contractors": 1,
      "annexes": [
        {
          "id": "0",
          "status": "made"
        },
        {
          "id": "A",
          "status": "made"
        },
        {
          "id": "B",
          "status": "missing_data"
        },
        {
          "id": "C",
          "status": "out"
        },
        {
          "id": "D",
          "status": "missing_data"
        },
        {
          "id": "E",
          "status": "not_asked"
        },
        {
          "id": "F",
          "status": "made"
        }
      ]
    }
  }
}

Get the Relatório Único yearly forms#

POST/v1/country/relatorio_unico.annual.getRead

Portugal: the yearly forms of one Portuguese legal entity's Relatório Único that Bizisy can't fill from its records — Anexo 0 (turnover, union members on 31 October, posted workers, employer associations, overtime, capital, optional spending and accounts) and Anexo D (how health and safety at work is organised, its staff and services, programmes and yes/no answers, per-establishment hours and accidents without leave) — with what Bizisy prefills: employees on 31 December and on average, per establishment the average workers, estimated hours and work accidents counted from time off (leave types marked as work accidents), and how many service providers Anexo F lists. year: the report being prepared by default. Over an API key or AI connection the names and numbers of health and safety staff are left out. Owners, admins, HR and roles with Payroll at View.

Who can call it
Manage key owner admin hr
Keys and apps
Without the names and numbers of health and safety staff and external services, and without work-accident counts.
MCP tool
country_relatorio_unico_annual_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • legal_entity_idstringrequired

    1–100 characters.

  • yearinteger

    From 2010 to 2100.

Returns

8 fields
  • legal_entityobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • yearintegerrequired
  • zeroobject | nullrequired

    Anexo 0's form; null until saved.

    19 fields
    • turnoverinteger | nullrequired

      VIII-1 volume de negócios: the year's turnover in whole euros.

      From 0 to 999999999999.

    • turnover_yearinteger | nullrequired

      The year the turnover refers to (default: the report's year).

      From 2000 to 2100.

    • union_membersinteger | nullrequired

      IV-1 workers in a trade union on 31 October (a count; Bizisy keeps no membership).

      From 0 to 99999.

    • posted_workersintegerrequired

      III-2.1 workers posted abroad in the year.

      From 0 to 99999.

    • postingsintegerrequired

      III-2.2 number of postings (0 with no posted workers).

      From 0 to 99999.

    • associationsstring[]required

      IV-2 employer associations the company belongs to (Relatório Único table 08 codes); empty: none.

      Up to 20 items. Pattern ^\d{4}$.

    • overtime"S" | "N"required

      V-1 was overtime worked in the year (S/N)?

    • overtime_list_endorsed"S" | "N"required

      V-2 with overtime: was the nominal list of who worked it (art. 227.º) endorsed by the workers' committee or union (S/N)?

    • others_31_decintegerrequired

      People working who are not employees (working owners and partners, unpaid family members) on 31 December.

      From 0 to 99999.

    • others_averageintegerrequired

      …and their average over the year.

      From 0 to 99999.

    • temp_31_octinteger | nullrequired

      From 0 to 99999.

    • temp_31_decinteger | nullrequired

      From 0 to 99999.

    • temp_averageinteger | nullrequired

      VI-1 temporary agency workers used: on 31 October, 31 December and the yearly average.

      From 0 to 99999.

    • capitalinteger | nullrequired

      VIII-2 share capital in euros.

      From 0 to 999999999999.

    • capital_private_ptnumber | nullrequired

      From 0 to 100.

    • capital_foreignnumber | nullrequired

      From 0 to 100.

    • capital_public_ptnumber | nullrequired

      From 0 to 100.

    • spendingobjectrequired

      Optional VIII-3 training financing (mont_remun_horas_form, rest_finan_ent, finan_fse, finan_outras_fontes) and VIII-4 health and safety spending (encarg_org_sst, encarg_org_esp_trab, encarg_aqui_bens, encarg_form, encarg_outros), whole euros; the totals are computed.

      9 fields
      • mont_remun_horas_forminteger

        From 0 to 999999999999.

      • rest_finan_entinteger

        From 0 to 999999999999.

      • finan_fseinteger

        From 0 to 999999999999.

      • finan_outras_fontesinteger

        From 0 to 999999999999.

      • encarg_org_sstinteger

        From 0 to 999999999999.

      • encarg_org_esp_trabinteger

        From 0 to 999999999999.

      • encarg_aqui_bensinteger

        From 0 to 999999999999.

      • encarg_forminteger

        From 0 to 999999999999.

      • encarg_outrosinteger

        From 0 to 999999999999.

    • accountsobjectrequired

      IX-1 for 10 or more workers on 31 October: vab, custos_pessoal, amort_exerc, provi_exerc, custos_perdas, impost_rend, res_liquido (whole euros, may be negative).

      7 fields
      • vabinteger

        From -9999999999 to 9999999999.

      • custos_pessoalinteger

        From -9999999999 to 9999999999.

      • amort_exercinteger

        From -9999999999 to 9999999999.

      • provi_exercinteger

        From -9999999999 to 9999999999.

      • custos_perdasinteger

        From -9999999999 to 9999999999.

      • impost_rendinteger

        From -9999999999 to 9999999999.

      • res_liquidointeger

        From -9999999999 to 9999999999.

  • sstobject | nullrequired

    Anexo D's form; null until saved. Over an API key or AI connection the staff names and numbers and the external services are left out.

    35 fields
    • safety"S" | "N"required

      II-1 were safety-at-work services organised?

    • health"S" | "N"required

      II-2 were health-at-work services organised?

    • together"C" | "S"required

      II-4 with both: organised together (C) or separately (S).

    • safety_modes"internal" | "common" | "external" | "employer" | "designated"[]required

      II-5.1 internal, common (serviço comum), external, employer, designated (trabalhador designado).

      Up to 5 items.

    • health_modes"internal" | "common" | "external" | "sns"[]required

      II-5.2 internal, common, external, sns (Serviço Nacional/Regional de Saúde).

      Up to 4 items.

    • complemented"S" | "N"required

      II-6 were the services complemented?

    • first_aid_workersintegerrequired

      II-3 workers in first aid, firefighting and evacuation (per establishment unless overridden).

      From 0 to 999.

    • nursesintegerrequired

      From 0 to 99.

    • other_staffintegerrequired

      From 0 to 99.

    • doctorsobject[]required

      III-1.2 occupational doctors: name, cédula profissional, monthly hours (HHH,MM).

      Up to 20 items.

      3 fields
      • namestringrequired

        1–70 characters.

      • licencestringrequired

        Pattern ^\d{1,5}$.

      • monthly_hoursstringrequired

        Pattern ^\d{1,3},\d{2}$.

    • techniciansobject[]required

      III-1.3 safety technicians (senior: técnico superior) with their CAP number.

      Up to 20 items.

      3 fields
      • namestringrequired

        1–70 characters.

      • capstringrequired

        3–40 characters.

      • seniorbooleanrequired
    • safety_headobject | nullrequired
      2 fields
      • nifstringrequired

        Pattern ^\d{9}$.

      • namestringrequired

        1–70 characters.

    • health_headobject | nullrequired
      2 fields
      • nifstringrequired

        Pattern ^\d{9}$.

      • namestringrequired

        1–70 characters.

    • employerobject | nullrequired
      2 fields
      • namestringrequired

        1–70 characters.

      • authorizationstringrequired

        Pattern ^\d{1,8}$.

    • designatedobject | nullrequired
      2 fields
      • namestringrequired

        1–70 characters.

      • authorizationstringrequired

        Pattern ^\d{1,8}$.

    • representativestring | nullrequired

      1–70 characters.

    • safety_servicesobject[]required

      Up to 20 items.

      3 fields
      • nifstringrequired

        Pattern ^\d{9}$.

      • namestring | nullrequired

        1–100 characters.

      • type"1" | "2" | "3" | "4"required

        Relatório Único table 37: 1 associativo, 2 cooperativo, 3 convencionado, 4 privado.

    • health_servicesobject[]required

      Up to 20 items.

      3 fields
      • nifstringrequired

        Pattern ^\d{9}$.

      • namestring | nullrequired

        1–100 characters.

      • type"1" | "2" | "3" | "4"required

        Relatório Único table 37: 1 associativo, 2 cooperativo, 3 convencionado, 4 privado.

    • prevention"S" | "N"required
    • promotion"S" | "N"required
    • surveillance"S" | "N"required
    • audits"S" | "N"required
    • inspections"S" | "N"required
    • information"S" | "N"required
    • consultation"S" | "N"required
    • training"S" | "N"required
    • risksobjectrequired
      6 fields
      • physical"S" | "N"required
      • chemical"S" | "N"required
      • biological"S" | "N"required
      • musculoskeletal"S" | "N"required
      • psychosocial"S" | "N"required
      • other"S" | "N"required
    • exams"S" | "N"required
    • complementary_exams"S" | "N"required
    • immunisation"S" | "N"required
    • health_promotion"S" | "N"required
    • diseases_reported"S" | "N"required
    • diseases_confirmed"S" | "N"required
    • no_accidentsbooleanrequired

      No leave type is marked as a work accident and there were none: confirm it (else Bizisy can't count them).

    • establishmentsobject[]required

      Per establishment (location): hours actually worked (overrides the estimate), first-aid workers, accidents without leave, fatal accidents, accidents of other workers there.

      Up to 200 items.

      6 fields
      • location_idstringrequired

        1–100 characters.

      • hours_workedinteger | nullrequired

        From 0 to 999999999.

      • first_aid_workersinteger | nullrequired

        From 0 to 999.

      • no_leaveobjectrequired
        2 fields
        • hintegerrequired

          From 0 to 9999.

        • mintegerrequired

          From 0 to 9999.

      • fatalobjectrequired
        2 fields
        • hintegerrequired

          From 0 to 9999.

        • mintegerrequired

          From 0 to 9999.

      • othersobjectrequired
        2 fields
        • hintegerrequired

          From 0 to 9999.

        • mintegerrequired

          From 0 to 9999.

  • providers_nonebooleanrequired

    Anexo F: confirmed there were no service providers in the year.

  • providersintegerrequired

    Service providers listed for the year.

  • prefillobjectrequired
    6 fields
    • employees_31_decemberintegerrequired
    • employees_averageintegerrequired
    • headcount_31_octoberintegerrequired

      With 10 or more, Anexo 0 asks for section IX (accounts).

    • timeoffbooleanrequired

      Time off is on: accidents are counted from it.

    • accident_typesintegerrequired

      Leave types marked as work accidents (0: Bizisy can't count accidents).

    • establishmentsobject[]required
      8 fields
      • location_idstring | nullrequired
      • namestring | nullrequired
      • ru_estabstring | nullrequired
      • employeesintegerrequired

        Yearly average of employees.

      • contractorsintegerrequired
      • hours_estimateintegerrequired

        Estimated hours worked (weekdays × weekly hours ÷ 5, less vacation, public holidays and work-accident days).

      • accidentsinteger | nullrequired

        Work accidents in the year counted from time off; null over an API key or AI connection and for roles without Private details.

      • days_lostinteger | nullrequired
  • updated_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/country/relatorio_unico.annual.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"legal_entity_id":"le1","year":2025}'
Response
{
  "data": {
    "legal_entity": {
      "id": "le1",
      "name": "Acme Portugal Lda"
    },
    "year": 2025,
    "zero": {
      "turnover": 1250000,
      "turnover_year": 2025,
      "union_members": 2,
      "posted_workers": 0,
      "postings": 0,
      "associations": [
        "0141"
      ],
      "overtime": "S",
      "overtime_list_endorsed": "N",
      "others_31_dec": 1,
      "others_average": 1,
      "temp_31_oct": null,
      "temp_31_dec": null,
      "temp_average": null,
      "capital": 50000,
      "capital_private_pt": 100,
      "capital_foreign": 0,
      "capital_public_pt": 0,
      "spending": {
        "encarg_org_sst": 1200
      },
      "accounts": {
        "vab": 640000,
        "custos_pessoal": 410000
      }
    },
    "sst": {
      "safety": "S",
      "health": "S",
      "together": "C",
      "safety_modes": [
        "external"
      ],
      "health_modes": [
        "external"
      ],
      "complemented": "N",
      "first_aid_workers": 2,
      "nurses": 0,
      "other_staff": 0,
      "doctors": [
        {
          "name": "Rita Lopes",
          "licence": "12345",
          "monthly_hours": "4,30"
        }
      ],
      "technicians": [
        {
          "name": "João Neves",
          "cap": "1234/0901/03/5",
          "senior": true
        }
      ],
      "safety_head": null,
      "health_head": null,
      "employer": null,
      "designated": null,
      "representative": "Ana Costa",
      "safety_services": [
        {
          "nif": "509999999",
          "name": "Segura SST Lda",
          "type": "4"
        }
      ],
      "health_services": [
        {
          "nif": "509999999",
          "name": "Segura SST Lda",
          "type": "4"
        }
      ],
      "prevention": "S",
      "promotion": "N",
      "surveillance": "S",
      "audits": "N",
      "inspections": "N",
      "information": "S",
      "consultation": "N",
      "training": "S",
      "risks": {
        "physical": "N",
        "chemical": "N",
        "biological": "N",
        "musculoskeletal": "S",
        "psychosocial": "N",
        "other": "N"
      },
      "exams": "S",
      "complementary_exams": "N",
      "immunisation": "N",
      "health_promotion": "N",
      "diseases_reported": "N",
      "diseases_confirmed": "N",
      "no_accidents": false,
      "establishments": [
        {
          "location_id": "l1",
          "hours_worked": 12400,
          "first_aid_workers": null,
          "no_leave": {
            "h": 0,
            "m": 1
          },
          "fatal": {
            "h": 0,
            "m": 0
          },
          "others": {
            "h": 0,
            "m": 0
          }
        }
      ]
    },
    "providers_none": false,
    "providers": 2,
    "prefill": {
      "employees_31_december": 12,
      "employees_average": 11,
      "headcount_31_october": 11,
      "timeoff": true,
      "accident_types": 1,
      "establishments": [
        {
          "location_id": "l1",
          "name": "Lisboa",
          "ru_estab": "987654",
          "employees": 8,
          "contractors": 1,
          "hours_estimate": 12290,
          "accidents": 1,
          "days_lost": 7
        },
        {
          "location_id": "l2",
          "name": "Porto",
          "ru_estab": null,
          "employees": 3,
          "contractors": 0,
          "hours_estimate": 4610,
          "accidents": 0,
          "days_lost": 0
        }
      ]
    },
    "updated_at": "2026-03-18T10:00:00.000Z"
  }
}

Save the Relatório Único yearly forms#

POST/v1/country/relatorio_unico.annual.setWrite

Portugal: saves one or more of a Portuguese legal entity's yearly Relatório Único forms for a year: zero (Anexo 0) and sst (Anexo D) are saved whole (null clears one); providers_none confirms there were no service providers (Anexo F; refused while providers are listed). Saving a form is HR confirming its answers; the files are made with country_relatorio_unico_generate. In the app only (Anexo D names health and safety staff). Owners, admins, HR and roles with Payroll at Edit.

Web app only
Refused for API keys and connected apps. The yearly forms name health and safety staff: they are saved in the app.
MCP tool
country_relatorio_unico_annual_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

  • legal_entity_idstringrequired

    1–100 characters.

  • yearintegerrequired

    From 2010 to 2100.

  • zeroobject | null
    19 fields
    • turnoverinteger | nullrequired

      VIII-1 volume de negócios: the year's turnover in whole euros.

      From 0 to 999999999999.

    • turnover_yearinteger | nullrequired

      The year the turnover refers to (default: the report's year).

      From 2000 to 2100.

    • union_membersinteger | nullrequired

      IV-1 workers in a trade union on 31 October (a count; Bizisy keeps no membership).

      From 0 to 99999.

    • posted_workersintegerrequired

      III-2.1 workers posted abroad in the year.

      From 0 to 99999.

    • postingsintegerrequired

      III-2.2 number of postings (0 with no posted workers).

      From 0 to 99999.

    • associationsstring[]required

      IV-2 employer associations the company belongs to (Relatório Único table 08 codes); empty: none.

      Up to 20 items. Pattern ^\d{4}$.

    • overtime"S" | "N"required

      V-1 was overtime worked in the year (S/N)?

    • overtime_list_endorsed"S" | "N"required

      V-2 with overtime: was the nominal list of who worked it (art. 227.º) endorsed by the workers' committee or union (S/N)?

    • others_31_decintegerrequired

      People working who are not employees (working owners and partners, unpaid family members) on 31 December.

      From 0 to 99999.

    • others_averageintegerrequired

      …and their average over the year.

      From 0 to 99999.

    • temp_31_octinteger | nullrequired

      From 0 to 99999.

    • temp_31_decinteger | nullrequired

      From 0 to 99999.

    • temp_averageinteger | nullrequired

      VI-1 temporary agency workers used: on 31 October, 31 December and the yearly average.

      From 0 to 99999.

    • capitalinteger | nullrequired

      VIII-2 share capital in euros.

      From 0 to 999999999999.

    • capital_private_ptnumber | nullrequired

      From 0 to 100.

    • capital_foreignnumber | nullrequired

      From 0 to 100.

    • capital_public_ptnumber | nullrequired

      From 0 to 100.

    • spendingobjectrequired

      Optional VIII-3 training financing (mont_remun_horas_form, rest_finan_ent, finan_fse, finan_outras_fontes) and VIII-4 health and safety spending (encarg_org_sst, encarg_org_esp_trab, encarg_aqui_bens, encarg_form, encarg_outros), whole euros; the totals are computed.

      9 fields
      • mont_remun_horas_forminteger

        From 0 to 999999999999.

      • rest_finan_entinteger

        From 0 to 999999999999.

      • finan_fseinteger

        From 0 to 999999999999.

      • finan_outras_fontesinteger

        From 0 to 999999999999.

      • encarg_org_sstinteger

        From 0 to 999999999999.

      • encarg_org_esp_trabinteger

        From 0 to 999999999999.

      • encarg_aqui_bensinteger

        From 0 to 999999999999.

      • encarg_forminteger

        From 0 to 999999999999.

      • encarg_outrosinteger

        From 0 to 999999999999.

    • accountsobjectrequired

      IX-1 for 10 or more workers on 31 October: vab, custos_pessoal, amort_exerc, provi_exerc, custos_perdas, impost_rend, res_liquido (whole euros, may be negative).

      7 fields
      • vabinteger

        From -9999999999 to 9999999999.

      • custos_pessoalinteger

        From -9999999999 to 9999999999.

      • amort_exercinteger

        From -9999999999 to 9999999999.

      • provi_exercinteger

        From -9999999999 to 9999999999.

      • custos_perdasinteger

        From -9999999999 to 9999999999.

      • impost_rendinteger

        From -9999999999 to 9999999999.

      • res_liquidointeger

        From -9999999999 to 9999999999.

  • sstobject | null
    35 fields
    • safety"S" | "N"required

      II-1 were safety-at-work services organised?

    • health"S" | "N"required

      II-2 were health-at-work services organised?

    • together"C" | "S"required

      II-4 with both: organised together (C) or separately (S).

    • safety_modes"internal" | "common" | "external" | "employer" | "designated"[]required

      II-5.1 internal, common (serviço comum), external, employer, designated (trabalhador designado).

      Up to 5 items.

    • health_modes"internal" | "common" | "external" | "sns"[]required

      II-5.2 internal, common, external, sns (Serviço Nacional/Regional de Saúde).

      Up to 4 items.

    • complemented"S" | "N"required

      II-6 were the services complemented?

    • first_aid_workersintegerrequired

      II-3 workers in first aid, firefighting and evacuation (per establishment unless overridden).

      From 0 to 999.

    • nursesintegerrequired

      From 0 to 99.

    • other_staffintegerrequired

      From 0 to 99.

    • doctorsobject[]required

      III-1.2 occupational doctors: name, cédula profissional, monthly hours (HHH,MM).

      Up to 20 items.

      3 fields
      • namestringrequired

        1–70 characters.

      • licencestringrequired

        Pattern ^\d{1,5}$.

      • monthly_hoursstringrequired

        Pattern ^\d{1,3},\d{2}$.

    • techniciansobject[]required

      III-1.3 safety technicians (senior: técnico superior) with their CAP number.

      Up to 20 items.

      3 fields
      • namestringrequired

        1–70 characters.

      • capstringrequired

        3–40 characters.

      • seniorbooleanrequired
    • safety_headobject | nullrequired
      2 fields
      • nifstringrequired

        Pattern ^\d{9}$.

      • namestringrequired

        1–70 characters.

    • health_headobject | nullrequired
      2 fields
      • nifstringrequired

        Pattern ^\d{9}$.

      • namestringrequired

        1–70 characters.

    • employerobject | nullrequired
      2 fields
      • namestringrequired

        1–70 characters.

      • authorizationstringrequired

        Pattern ^\d{1,8}$.

    • designatedobject | nullrequired
      2 fields
      • namestringrequired

        1–70 characters.

      • authorizationstringrequired

        Pattern ^\d{1,8}$.

    • representativestring | nullrequired

      1–70 characters.

    • safety_servicesobject[]required

      Up to 20 items.

      3 fields
      • nifstringrequired

        Pattern ^\d{9}$.

      • namestring | nullrequired

        1–100 characters.

      • type"1" | "2" | "3" | "4"required

        Relatório Único table 37: 1 associativo, 2 cooperativo, 3 convencionado, 4 privado.

    • health_servicesobject[]required

      Up to 20 items.

      3 fields
      • nifstringrequired

        Pattern ^\d{9}$.

      • namestring | nullrequired

        1–100 characters.

      • type"1" | "2" | "3" | "4"required

        Relatório Único table 37: 1 associativo, 2 cooperativo, 3 convencionado, 4 privado.

    • prevention"S" | "N"required
    • promotion"S" | "N"required
    • surveillance"S" | "N"required
    • audits"S" | "N"required
    • inspections"S" | "N"required
    • information"S" | "N"required
    • consultation"S" | "N"required
    • training"S" | "N"required
    • risksobjectrequired
      6 fields
      • physical"S" | "N"required
      • chemical"S" | "N"required
      • biological"S" | "N"required
      • musculoskeletal"S" | "N"required
      • psychosocial"S" | "N"required
      • other"S" | "N"required
    • exams"S" | "N"required
    • complementary_exams"S" | "N"required
    • immunisation"S" | "N"required
    • health_promotion"S" | "N"required
    • diseases_reported"S" | "N"required
    • diseases_confirmed"S" | "N"required
    • no_accidentsbooleanrequired

      No leave type is marked as a work accident and there were none: confirm it (else Bizisy can't count them).

    • establishmentsobject[]required

      Per establishment (location): hours actually worked (overrides the estimate), first-aid workers, accidents without leave, fatal accidents, accidents of other workers there.

      Up to 200 items.

      6 fields
      • location_idstringrequired

        1–100 characters.

      • hours_workedinteger | nullrequired

        From 0 to 999999999.

      • first_aid_workersinteger | nullrequired

        From 0 to 999.

      • no_leaveobjectrequired
        2 fields
        • hintegerrequired

          From 0 to 9999.

        • mintegerrequired

          From 0 to 9999.

      • fatalobjectrequired
        2 fields
        • hintegerrequired

          From 0 to 9999.

        • mintegerrequired

          From 0 to 9999.

      • othersobjectrequired
        2 fields
        • hintegerrequired

          From 0 to 9999.

        • mintegerrequired

          From 0 to 9999.

  • providers_noneboolean

Returns

8 fields
  • legal_entityobjectrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • yearintegerrequired
  • zeroobject | nullrequired

    Anexo 0's form; null until saved.

    19 fields
    • turnoverinteger | nullrequired

      VIII-1 volume de negócios: the year's turnover in whole euros.

      From 0 to 999999999999.

    • turnover_yearinteger | nullrequired

      The year the turnover refers to (default: the report's year).

      From 2000 to 2100.

    • union_membersinteger | nullrequired

      IV-1 workers in a trade union on 31 October (a count; Bizisy keeps no membership).

      From 0 to 99999.

    • posted_workersintegerrequired

      III-2.1 workers posted abroad in the year.

      From 0 to 99999.

    • postingsintegerrequired

      III-2.2 number of postings (0 with no posted workers).

      From 0 to 99999.

    • associationsstring[]required

      IV-2 employer associations the company belongs to (Relatório Único table 08 codes); empty: none.

      Up to 20 items. Pattern ^\d{4}$.

    • overtime"S" | "N"required

      V-1 was overtime worked in the year (S/N)?

    • overtime_list_endorsed"S" | "N"required

      V-2 with overtime: was the nominal list of who worked it (art. 227.º) endorsed by the workers' committee or union (S/N)?

    • others_31_decintegerrequired

      People working who are not employees (working owners and partners, unpaid family members) on 31 December.

      From 0 to 99999.

    • others_averageintegerrequired

      …and their average over the year.

      From 0 to 99999.

    • temp_31_octinteger | nullrequired

      From 0 to 99999.

    • temp_31_decinteger | nullrequired

      From 0 to 99999.

    • temp_averageinteger | nullrequired

      VI-1 temporary agency workers used: on 31 October, 31 December and the yearly average.

      From 0 to 99999.

    • capitalinteger | nullrequired

      VIII-2 share capital in euros.

      From 0 to 999999999999.

    • capital_private_ptnumber | nullrequired

      From 0 to 100.

    • capital_foreignnumber | nullrequired

      From 0 to 100.

    • capital_public_ptnumber | nullrequired

      From 0 to 100.

    • spendingobjectrequired

      Optional VIII-3 training financing (mont_remun_horas_form, rest_finan_ent, finan_fse, finan_outras_fontes) and VIII-4 health and safety spending (encarg_org_sst, encarg_org_esp_trab, encarg_aqui_bens, encarg_form, encarg_outros), whole euros; the totals are computed.

      9 fields
      • mont_remun_horas_forminteger

        From 0 to 999999999999.

      • rest_finan_entinteger

        From 0 to 999999999999.

      • finan_fseinteger

        From 0 to 999999999999.

      • finan_outras_fontesinteger

        From 0 to 999999999999.

      • encarg_org_sstinteger

        From 0 to 999999999999.

      • encarg_org_esp_trabinteger

        From 0 to 999999999999.

      • encarg_aqui_bensinteger

        From 0 to 999999999999.

      • encarg_forminteger

        From 0 to 999999999999.

      • encarg_outrosinteger

        From 0 to 999999999999.

    • accountsobjectrequired

      IX-1 for 10 or more workers on 31 October: vab, custos_pessoal, amort_exerc, provi_exerc, custos_perdas, impost_rend, res_liquido (whole euros, may be negative).

      7 fields
      • vabinteger

        From -9999999999 to 9999999999.

      • custos_pessoalinteger

        From -9999999999 to 9999999999.

      • amort_exercinteger

        From -9999999999 to 9999999999.

      • provi_exercinteger

        From -9999999999 to 9999999999.

      • custos_perdasinteger

        From -9999999999 to 9999999999.

      • impost_rendinteger

        From -9999999999 to 9999999999.

      • res_liquidointeger

        From -9999999999 to 9999999999.

  • sstobject | nullrequired

    Anexo D's form; null until saved. Over an API key or AI connection the staff names and numbers and the external services are left out.

    35 fields
    • safety"S" | "N"required

      II-1 were safety-at-work services organised?

    • health"S" | "N"required

      II-2 were health-at-work services organised?

    • together"C" | "S"required

      II-4 with both: organised together (C) or separately (S).

    • safety_modes"internal" | "common" | "external" | "employer" | "designated"[]required

      II-5.1 internal, common (serviço comum), external, employer, designated (trabalhador designado).

      Up to 5 items.

    • health_modes"internal" | "common" | "external" | "sns"[]required

      II-5.2 internal, common, external, sns (Serviço Nacional/Regional de Saúde).

      Up to 4 items.

    • complemented"S" | "N"required

      II-6 were the services complemented?

    • first_aid_workersintegerrequired

      II-3 workers in first aid, firefighting and evacuation (per establishment unless overridden).

      From 0 to 999.

    • nursesintegerrequired

      From 0 to 99.

    • other_staffintegerrequired

      From 0 to 99.

    • doctorsobject[]required

      III-1.2 occupational doctors: name, cédula profissional, monthly hours (HHH,MM).

      Up to 20 items.

      3 fields
      • namestringrequired

        1–70 characters.

      • licencestringrequired

        Pattern ^\d{1,5}$.

      • monthly_hoursstringrequired

        Pattern ^\d{1,3},\d{2}$.

    • techniciansobject[]required

      III-1.3 safety technicians (senior: técnico superior) with their CAP number.

      Up to 20 items.

      3 fields
      • namestringrequired

        1–70 characters.

      • capstringrequired

        3–40 characters.

      • seniorbooleanrequired
    • safety_headobject | nullrequired
      2 fields
      • nifstringrequired

        Pattern ^\d{9}$.

      • namestringrequired

        1–70 characters.

    • health_headobject | nullrequired
      2 fields
      • nifstringrequired

        Pattern ^\d{9}$.

      • namestringrequired

        1–70 characters.

    • employerobject | nullrequired
      2 fields
      • namestringrequired

        1–70 characters.

      • authorizationstringrequired

        Pattern ^\d{1,8}$.

    • designatedobject | nullrequired
      2 fields
      • namestringrequired

        1–70 characters.

      • authorizationstringrequired

        Pattern ^\d{1,8}$.

    • representativestring | nullrequired

      1–70 characters.

    • safety_servicesobject[]required

      Up to 20 items.

      3 fields
      • nifstringrequired

        Pattern ^\d{9}$.

      • namestring | nullrequired

        1–100 characters.

      • type"1" | "2" | "3" | "4"required

        Relatório Único table 37: 1 associativo, 2 cooperativo, 3 convencionado, 4 privado.

    • health_servicesobject[]required

      Up to 20 items.

      3 fields
      • nifstringrequired

        Pattern ^\d{9}$.

      • namestring | nullrequired

        1–100 characters.

      • type"1" | "2" | "3" | "4"required

        Relatório Único table 37: 1 associativo, 2 cooperativo, 3 convencionado, 4 privado.

    • prevention"S" | "N"required
    • promotion"S" | "N"required
    • surveillance"S" | "N"required
    • audits"S" | "N"required
    • inspections"S" | "N"required
    • information"S" | "N"required
    • consultation"S" | "N"required
    • training"S" | "N"required
    • risksobjectrequired
      6 fields
      • physical"S" | "N"required
      • chemical"S" | "N"required
      • biological"S" | "N"required
      • musculoskeletal"S" | "N"required
      • psychosocial"S" | "N"required
      • other"S" | "N"required
    • exams"S" | "N"required
    • complementary_exams"S" | "N"required
    • immunisation"S" | "N"required
    • health_promotion"S" | "N"required
    • diseases_reported"S" | "N"required
    • diseases_confirmed"S" | "N"required
    • no_accidentsbooleanrequired

      No leave type is marked as a work accident and there were none: confirm it (else Bizisy can't count them).

    • establishmentsobject[]required

      Per establishment (location): hours actually worked (overrides the estimate), first-aid workers, accidents without leave, fatal accidents, accidents of other workers there.

      Up to 200 items.

      6 fields
      • location_idstringrequired

        1–100 characters.

      • hours_workedinteger | nullrequired

        From 0 to 999999999.

      • first_aid_workersinteger | nullrequired

        From 0 to 999.

      • no_leaveobjectrequired
        2 fields
        • hintegerrequired

          From 0 to 9999.

        • mintegerrequired

          From 0 to 9999.

      • fatalobjectrequired
        2 fields
        • hintegerrequired

          From 0 to 9999.

        • mintegerrequired

          From 0 to 9999.

      • othersobjectrequired
        2 fields
        • hintegerrequired

          From 0 to 9999.

        • mintegerrequired

          From 0 to 9999.

  • providers_nonebooleanrequired

    Anexo F: confirmed there were no service providers in the year.

  • providersintegerrequired

    Service providers listed for the year.

  • prefillobjectrequired
    6 fields
    • employees_31_decemberintegerrequired
    • employees_averageintegerrequired
    • headcount_31_octoberintegerrequired

      With 10 or more, Anexo 0 asks for section IX (accounts).

    • timeoffbooleanrequired

      Time off is on: accidents are counted from it.

    • accident_typesintegerrequired

      Leave types marked as work accidents (0: Bizisy can't count accidents).

    • establishmentsobject[]required
      8 fields
      • location_idstring | nullrequired
      • namestring | nullrequired
      • ru_estabstring | nullrequired
      • employeesintegerrequired

        Yearly average of employees.

      • contractorsintegerrequired
      • hours_estimateintegerrequired

        Estimated hours worked (weekdays × weekly hours ÷ 5, less vacation, public holidays and work-accident days).

      • accidentsinteger | nullrequired

        Work accidents in the year counted from time off; null over an API key or AI connection and for roles without Private details.

      • days_lostinteger | nullrequired
  • updated_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/country/relatorio_unico.annual.set \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "legal_entity_id": "le1",
  "year": 2025,
  "sst": {
    "safety": "S",
    "health": "S",
    "together": "C",
    "safety_modes": [
      "external"
    ],
    "health_modes": [
      "external"
    ],
    "complemented": "N",
    "first_aid_workers": 2,
    "nurses": 0,
    "other_staff": 0,
    "doctors": [
      {
        "name": "Rita Lopes",
        "licence": "12345",
        "monthly_hours": "4,30"
      }
    ],
    "technicians": [
      {
        "name": "João Neves",
        "cap": "1234/0901/03/5",
        "senior": true
      }
    ],
    "safety_head": null,
    "health_head": null,
    "employer": null,
    "designated": null,
    "representative": "Ana Costa",
    "safety_services": [
      {
        "nif": "509999999",
        "name": "Segura SST Lda",
        "type": "4"
      }
    ],
    "health_services": [
      {
        "nif": "509999999",
        "name": "Segura SST Lda",
        "type": "4"
      }
    ],
    "prevention": "S",
    "promotion": "N",
    "surveillance": "S",
    "audits": "N",
    "inspections": "N",
    "information": "S",
    "consultation": "N",
    "training": "S",
    "risks": {
      "physical": "N",
      "chemical": "N",
      "biological": "N",
      "musculoskeletal": "S",
      "psychosocial": "N",
      "other": "N"
    },
    "exams": "S",
    "complementary_exams": "N",
    "immunisation": "N",
    "health_promotion": "N",
    "diseases_reported": "N",
    "diseases_confirmed": "N",
    "no_accidents": false,
    "establishments": [
      {
        "location_id": "l1",
        "hours_worked": 12400,
        "first_aid_workers": null,
        "no_leave": {
          "h": 0,
          "m": 1
        },
        "fatal": {
          "h": 0,
          "m": 0
        },
        "others": {
          "h": 0,
          "m": 0
        }
      }
    ]
  },
  "providers_none": false
}'
Response
{
  "data": {
    "legal_entity": {
      "id": "le1",
      "name": "Acme Portugal Lda"
    },
    "year": 2025,
    "zero": {
      "turnover": 1250000,
      "turnover_year": 2025,
      "union_members": 2,
      "posted_workers": 0,
      "postings": 0,
      "associations": [
        "0141"
      ],
      "overtime": "S",
      "overtime_list_endorsed": "N",
      "others_31_dec": 1,
      "others_average": 1,
      "temp_31_oct": null,
      "temp_31_dec": null,
      "temp_average": null,
      "capital": 50000,
      "capital_private_pt": 100,
      "capital_foreign": 0,
      "capital_public_pt": 0,
      "spending": {
        "encarg_org_sst": 1200
      },
      "accounts": {
        "vab": 640000,
        "custos_pessoal": 410000
      }
    },
    "sst": {
      "safety": "S",
      "health": "S",
      "together": "C",
      "safety_modes": [
        "external"
      ],
      "health_modes": [
        "external"
      ],
      "complemented": "N",
      "first_aid_workers": 2,
      "nurses": 0,
      "other_staff": 0,
      "doctors": [
        {
          "name": "Rita Lopes",
          "licence": "12345",
          "monthly_hours": "4,30"
        }
      ],
      "technicians": [
        {
          "name": "João Neves",
          "cap": "1234/0901/03/5",
          "senior": true
        }
      ],
      "safety_head": null,
      "health_head": null,
      "employer": null,
      "designated": null,
      "representative": "Ana Costa",
      "safety_services": [
        {
          "nif": "509999999",
          "name": "Segura SST Lda",
          "type": "4"
        }
      ],
      "health_services": [
        {
          "nif": "509999999",
          "name": "Segura SST Lda",
          "type": "4"
        }
      ],
      "prevention": "S",
      "promotion": "N",
      "surveillance": "S",
      "audits": "N",
      "inspections": "N",
      "information": "S",
      "consultation": "N",
      "training": "S",
      "risks": {
        "physical": "N",
        "chemical": "N",
        "biological": "N",
        "musculoskeletal": "S",
        "psychosocial": "N",
        "other": "N"
      },
      "exams": "S",
      "complementary_exams": "N",
      "immunisation": "N",
      "health_promotion": "N",
      "diseases_reported": "N",
      "diseases_confirmed": "N",
      "no_accidents": false,
      "establishments": [
        {
          "location_id": "l1",
          "hours_worked": 12400,
          "first_aid_workers": null,
          "no_leave": {
            "h": 0,
            "m": 1
          },
          "fatal": {
            "h": 0,
            "m": 0
          },
          "others": {
            "h": 0,
            "m": 0
          }
        }
      ]
    },
    "providers_none": false,
    "providers": 2,
    "prefill": {
      "employees_31_december": 12,
      "employees_average": 11,
      "headcount_31_october": 11,
      "timeoff": true,
      "accident_types": 1,
      "establishments": [
        {
          "location_id": "l1",
          "name": "Lisboa",
          "ru_estab": "987654",
          "employees": 8,
          "contractors": 1,
          "hours_estimate": 12290,
          "accidents": 1,
          "days_lost": 7
        },
        {
          "location_id": "l2",
          "name": "Porto",
          "ru_estab": null,
          "employees": 3,
          "contractors": 0,
          "hours_estimate": 4610,
          "accidents": 0,
          "days_lost": 0
        }
      ]
    },
    "updated_at": "2026-03-18T10:00:00.000Z"
  }
}

List Relatório Único service providers#

POST/v1/country/relatorio_unico.providers.listRead

Portugal: the service providers of one Portuguese legal entity in a year, for the Relatório Único's Anexo F (prestadores de serviço): NIF, name, person (1) or company (2), social security scheme and NISS, activity (CAE or CIRS code) and each engagement (months, hours for a person, workers placed for a company). Pages of up to 500 (limit, default 200) in id order: pass next as after for the next page; total counts them all. none: HR confirmed there were none. Over an API key or AI connection a person's NIF, NISS and name are left out. Owners, admins, HR and roles with Payroll at View.

Who can call it
Manage key owner admin hr
Keys and apps
Without a self-employed provider's NIF, NISS and name, or any NISS.
MCP tool
country_relatorio_unico_providers_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • legal_entity_idstringrequired

    1–100 characters.

  • yearintegerrequired

    From 2010 to 2100.

  • limitinteger

    From 1 to 500.

  • afterstring

    1–100 characters.

Returns

  • nonebooleanrequired
  • itemsobject[]required

    A person's (kind 1) NIF, NISS and name are private: null over an API key or AI connection; a company's NISS too.

    11 fields
    • idstringrequired
    • nifstring | nullrequired
    • namestring | nullrequired
    • kind"1" | "2"required
    • scheme"1" | "8"required
    • nissstring | nullrequired
    • activity_type"1" | "2"required
    • activity_codestringrequired
    • engagementsobject[]required

      1–50 items.

      4 fields
      • startstring | nullrequired

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

      • endstring | nullrequired

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

      • hoursinteger | nullrequired

        A person: hours on the work.

        From 1 to 9999.

      • workersinteger | nullrequired

        A company: workers it placed.

        From 1 to 99999.

    • source"app" | "csv"required
    • updated_atstringrequired
  • nextstring | nullrequired

    The after of the next page; null on the last.

  • totalintegerrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/country/relatorio_unico.providers.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"legal_entity_id":"le1","year":2025,"limit":100,"after":"pr1"}'
Response
{
  "data": {
    "none": false,
    "items": [
      {
        "id": "pr1",
        "nif": "212345672",
        "name": "Marta Design",
        "kind": "1",
        "scheme": "1",
        "niss": "12345678902",
        "activity_type": "2",
        "activity_code": "1002",
        "engagements": [
          {
            "start": "2025-02",
            "end": "2025-04",
            "hours": 120,
            "workers": null
          }
        ],
        "source": "app",
        "updated_at": "2026-03-18T10:00:00.000Z"
      },
      {
        "id": "pr2",
        "nif": "510000002",
        "name": "Limpa Tudo SA",
        "kind": "2",
        "scheme": "1",
        "niss": "20000000019",
        "activity_type": "1",
        "activity_code": "81210",
        "engagements": [
          {
            "start": "2025-01",
            "end": "2025-12",
            "hours": null,
            "workers": 3
          }
        ],
        "source": "csv",
        "updated_at": "2026-03-18T10:00:00.000Z"
      }
    ],
    "next": null,
    "total": 2
  }
}

Save a Relatório Único service provider#

POST/v1/country/relatorio_unico.providers.saveWrite

Portugal: adds a service provider to a Portuguese legal entity's Anexo F list for a year, or changes one (provider_id). Checked as the Relatório Único platform checks it: a valid NIF (9 digits, check digit, not starting with 0, 4 or 8; not the entity's own; once per list), the NISS (11 digits with a valid check digit with Segurança Social), a name of 3–70 characters, a CAE (5 digits) or CIRS (4 digits) code, 1–50 engagements in the year (hours only for a person, workers placed only for a company). At most 5000 per entity and year. In the app only. Owners, admins, HR and roles with Payroll at Edit.

Web app only
Refused for API keys and connected apps. Service providers hold private identifiers: they are entered in the app.
MCP tool
country_relatorio_unico_providers_save 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

  • legal_entity_idstringrequired

    1–100 characters.

  • yearintegerrequired

    From 2010 to 2100.

  • provider_idstring

    1–100 characters.

  • nifstringrequired

    Pattern ^\d{9}$.

  • namestringrequired

    3–70 characters.

  • kind"1" | "2"required

    Table 54: 1 a person (singular), 2 a company (coletivo).

  • scheme"1" | "8"required

    Table 56: 1 Segurança Social, 8 another scheme.

  • nissstringrequired

    NISS (11 digits with Segurança Social) or the other scheme's number.

    1–20 characters.

  • activity_type"1" | "2"required

    Table 57: 1 CAE, 2 CIRS.

  • activity_codestringrequired

    Pattern ^\d{4,5}$.

  • engagementsobject[]required

    1–50 items.

    4 fields
    • startstring | nullrequired

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

    • endstring | nullrequired

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

    • hoursinteger | nullrequired

      A person: hours on the work.

      From 1 to 9999.

    • workersinteger | nullrequired

      A company: workers it placed.

      From 1 to 99999.

Returns

11 fields
  • idstringrequired
  • nifstring | nullrequired
  • namestring | nullrequired
  • kind"1" | "2"required
  • scheme"1" | "8"required
  • nissstring | nullrequired
  • activity_type"1" | "2"required
  • activity_codestringrequired
  • engagementsobject[]required

    1–50 items.

    4 fields
    • startstring | nullrequired

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

    • endstring | nullrequired

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

    • hoursinteger | nullrequired

      A person: hours on the work.

      From 1 to 9999.

    • workersinteger | nullrequired

      A company: workers it placed.

      From 1 to 99999.

  • source"app" | "csv"required
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/country/relatorio_unico.providers.save \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "legal_entity_id": "le1",
  "year": 2025,
  "provider_id": "pr1",
  "nif": "212345672",
  "name": "Marta Design",
  "kind": "1",
  "scheme": "1",
  "niss": "12345678902",
  "activity_type": "2",
  "activity_code": "1002",
  "engagements": [
    {
      "start": "2025-02",
      "end": "2025-04",
      "hours": 120,
      "workers": null
    }
  ]
}'
Response
{
  "data": {
    "id": "pr1",
    "nif": "212345672",
    "name": "Marta Design",
    "kind": "1",
    "scheme": "1",
    "niss": "12345678902",
    "activity_type": "2",
    "activity_code": "1002",
    "engagements": [
      {
        "start": "2025-02",
        "end": "2025-04",
        "hours": 120,
        "workers": null
      }
    ],
    "source": "app",
    "updated_at": "2026-03-18T10:00:00.000Z"
  }
}

Remove a Relatório Único service provider#

POST/v1/country/relatorio_unico.providers.removeWrite

Portugal: removes service providers from a Portuguese legal entity's Anexo F list for a year (provider_ids, up to 200; or all: true, which removes up to 200 a call and says more: true until the list is empty). In the app only. Owners, admins, HR and roles with Payroll at Edit.

Web app only
Refused for API keys and connected apps. The service providers list is changed in the app.
MCP tool
country_relatorio_unico_providers_remove 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

  • legal_entity_idstringrequired

    1–100 characters.

  • yearintegerrequired

    From 2010 to 2100.

  • provider_idsstring[]

    1–100 characters. 1–200 items.

  • alltrue

Returns

  • removedintegerrequired
  • morebooleanrequired

    all: providers are left; call it again.

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/country/relatorio_unico.providers.remove \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"legal_entity_id":"le1","year":2025,"provider_ids":["pr1"]}'
Response
{
  "data": {
    "removed": 1,
    "more": false
  }
}

Import Relatório Único service providers#

POST/v1/country/relatorio_unico.providers.importWrite

Portugal: adds up to 1000 rows of service providers to a Portuguese legal entity's Anexo F list for a year (from a spreadsheet: one row per provider and engagement). Columns: nif, name, type (singular or company; 1 or 2), scheme (social_security or other; default social_security), niss, activity_type (cae or cirs; default by the code's length), activity_code, start and end (YYYY-MM in the year), hours (a person) or workers (a company). Rows with the same NIF are one provider with several engagements; a NIF already in the list is replaced. All or nothing: run it as a dry run first to see each row's outcome; the real run refuses if any row has a problem. A real run saves at most 200 new or changed providers; left says how many remain: send the same rows again until left is 0 (providers already saved are skipped). In the app only. Owners, admins, HR and roles with Payroll at Edit.

Web app only
Refused for API keys and connected apps. Service providers hold private identifiers: they are imported in the app.
MCP tool
country_relatorio_unico_providers_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

  • legal_entity_idstringrequired

    1–100 characters.

  • yearintegerrequired

    From 2010 to 2100.

  • rowsobject[]required

    1–1000 items.

    11 fields
    • nifstringrequired

      Up to 40 characters.

    • namestringrequired

      Up to 200 characters.

    • typestringrequired

      Up to 40 characters.

    • schemestring

      Up to 40 characters.

    • nissstringrequired

      Up to 40 characters.

    • activity_typestring

      Up to 20 characters.

    • activity_codestringrequired

      Up to 20 characters.

    • startstring

      Up to 20 characters.

    • endstring

      Up to 20 characters.

    • hoursstring

      Up to 20 characters.

    • workersstring

      Up to 20 characters.

Returns

  • createdintegerrequired
  • updatedintegerrequired
  • leftintegerrequired

    New or changed providers not saved by this call: send the same rows again.

  • rowsobject[]required
    4 fields
    • rowintegerrequired

      1 = the first data row.

    • okbooleanrequired
    • codestring | nullrequired
    • problemstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/country/relatorio_unico.providers.import \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "legal_entity_id": "le1",
  "year": 2025,
  "rows": [
    {
      "nif": "212345672",
      "name": "Marta Design",
      "type": "singular",
      "niss": "12345678902",
      "activity_code": "1002",
      "start": "2025-02",
      "end": "2025-04",
      "hours": "120"
    }
  ]
}'
Response
{
  "data": {
    "created": 1,
    "updated": 0,
    "left": 0,
    "rows": [
      {
        "row": 1,
        "ok": true,
        "code": null,
        "problem": null
      }
    ]
  }
}

Get the vacation map#

POST/v1/country/vacation_map.getRead

The statutory vacation map (Portugal: mapa de férias, Código do Trabalho art. 241.º n.º 9 — made by 15 April and kept posted at each workplace until 31 October) of each legal entity whose country asks for one, per workplace: everyone employed there in the year with their approved vacation (start, end, working days) from time off, bookings still waiting for approval, its state (due, overdue, posted, changed since posting) and the posted versions. Names and dates only. Owners, admins, HR and roles with Payroll at View (an accounting firm's Accountant role).

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

Input

  • yearinteger

    Default: this year.

    From 2020 to 2100.

  • legal_entity_idstring

    1–100 characters.

Returns

  • as_ofstringrequired
  • yearintegerrequired
  • entitiesobject[]required
    8 fields
    • legal_entityobjectrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • countrystringrequired
    • yearintegerrequired
    • bystringrequired

      Made and posted by this day.

    • untilstringrequired

      Kept posted until this day.

    • lawstringrequired
    • source_urlstringrequired
    • timeoffbooleanrequired

      False: time off is not on, so the map has no bookings.

    • locationsobject[]required
      9 fields
      • location_idstring | nullrequired
      • namestringrequired

        The workplace; empty for people without a location.

      • rowsobject[]required

        The live map: each person with their approved vacation periods (start, end, working days).

        4 fields
        • person_idstring | nullrequired
        • namestringrequired
        • periodsobject[]required
          3 fields
          • startstringrequired
          • endstringrequired
          • daysnumberrequired
        • daysnumberrequired
      • peopleintegerrequired
      • pendingintegerrequired

        Vacation bookings not approved yet (not on the map).

      • state"not_due" | "due" | "overdue" | "posted" | "changed" | "closed"required

        not_due (more than a month before the deadline), due, overdue, posted, changed (bookings changed since the last posted version), closed (after the posting period).

      • changedbooleanrequired
      • postedobject | nullrequired
        2 fields
        • versionintegerrequired
        • posted_onstringrequired
      • versionsobject[]required
        3 fields
        • versionintegerrequired
        • posted_onstringrequired
        • created_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/country/vacation_map.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":2026,"legal_entity_id":"le1"}'
Response
{
  "data": {
    "as_of": "2026-03-20",
    "year": 2026,
    "entities": [
      {
        "legal_entity": {
          "id": "le1",
          "name": "Acme Portugal Lda",
          "country": "PT"
        },
        "year": 2026,
        "by": "2026-04-15",
        "until": "2026-10-31",
        "law": "Código do Trabalho, art. 241.º n.º 9",
        "source_url": "https://www.pgdlisboa.pt/leis/lei_mostra_articulado.php?artigo_id=1047A0241&nid=1047&tabela=leis",
        "timeoff": true,
        "locations": [
          {
            "location_id": "l1",
            "name": "Lisboa",
            "people": 3,
            "pending": 1,
            "state": "changed",
            "changed": true,
            "posted": {
              "version": 1,
              "posted_on": "2026-03-30"
            },
            "versions": [
              {
                "version": 1,
                "posted_on": "2026-03-30",
                "created_at": "2026-03-30T09:00:00.000Z"
              }
            ],
            "rows": [
              {
                "person_id": "p1",
                "name": "Ana Ferreira",
                "periods": [
                  {
                    "start": "2026-08-03",
                    "end": "2026-08-21",
                    "days": 15
                  },
                  {
                    "start": "2026-12-21",
                    "end": "2026-12-24",
                    "days": 4
                  }
                ],
                "days": 19
              },
              {
                "person_id": "p2",
                "name": "Beatriz Lopes",
                "periods": [
                  {
                    "start": "2026-07-13",
                    "end": "2026-07-31",
                    "days": 15
                  }
                ],
                "days": 15
              },
              {
                "person_id": "p3",
                "name": "Rui Costa",
                "periods": [],
                "days": 0
              }
            ]
          },
          {
            "location_id": "l2",
            "name": "Porto",
            "people": 1,
            "pending": 0,
            "state": "due",
            "changed": false,
            "posted": null,
            "versions": [],
            "rows": [
              {
                "person_id": "p4",
                "name": "Inês Martins",
                "periods": [
                  {
                    "start": "2026-09-07",
                    "end": "2026-09-18",
                    "days": 10
                  }
                ],
                "days": 10
              }
            ]
          }
        ]
      }
    ]
  }
}

Get a posted version of the vacation map#

POST/v1/country/vacation_map.versionRead

One posted version of a workplace's vacation map, as it was posted (to print it again or compare). Owners, admins, HR and roles with Payroll at View.

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

Input

  • legal_entity_idstringrequired

    1–100 characters.

  • location_idstring | nullrequired

    The workplace (location id), or null for people without a location.

    1–100 characters.

  • yearintegerrequired

    From 2020 to 2100.

  • versionintegerrequired

    From 1 to 50.

Returns

  • versionintegerrequired
  • posted_onstringrequired
  • rowsobject[]required
    4 fields
    • person_idstring | nullrequired
    • namestringrequired
    • periodsobject[]required
      3 fields
      • startstringrequired
      • endstringrequired
      • daysnumberrequired
    • daysnumberrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/country/vacation_map.version \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"legal_entity_id":"le1","location_id":"l1","year":2026,"version":1}'
Response
{
  "data": {
    "version": 1,
    "posted_on": "2026-03-30",
    "rows": [
      {
        "person_id": "p1",
        "name": "Ana Ferreira",
        "periods": [
          {
            "start": "2026-08-03",
            "end": "2026-08-21",
            "days": 15
          },
          {
            "start": "2026-12-21",
            "end": "2026-12-24",
            "days": 4
          }
        ],
        "days": 19
      },
      {
        "person_id": "p2",
        "name": "Beatriz Lopes",
        "periods": [
          {
            "start": "2026-07-13",
            "end": "2026-07-31",
            "days": 15
          }
        ],
        "days": 15
      },
      {
        "person_id": "p3",
        "name": "Rui Costa",
        "periods": [],
        "days": 0
      }
    ]
  }
}

Mark the vacation map as posted#

POST/v1/country/vacation_map.postWrite

Records that a workplace's vacation map was printed and posted (on posted_on, default today): the map as it is now becomes the next version, kept as posted. Refused when nothing changed since the last posted version. Bizisy posts nothing itself: a person puts the printed map up at the workplace. Owners, admins and HR.

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

    1–100 characters.

  • location_idstring | nullrequired

    The workplace (location id), or null for people without a location.

    1–100 characters.

  • yearintegerrequired

    From 2020 to 2100.

  • posted_onstring

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

Returns

  • versionintegerrequired
  • posted_onstringrequired
  • peopleintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/country/vacation_map.post \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "legal_entity_id": "le1",
  "location_id": null,
  "year": 2026,
  "posted_on": "2026-03-30"
}'
Response
{
  "data": {
    "version": 2,
    "posted_on": "2026-03-30",
    "people": 3
  }
}

Right to disconnect policy#

POST/v1/country/disconnect.getRead

The company's right-to-disconnect policy: the mode (law: quiet hours where each country's law asks for them, the default; on: for everyone; off: only where the law requires them), the policy text people see, and for each country the company employs people in, its law, headcount and whether quiet hours apply. With quiet hours, non-urgent emails and push notifications to an employee outside their working time (work schedule, shifts, location time zone) wait until their next working period. Owners, admins and HR.

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

Input

No input: send {}.

Returns

  • mode"law" | "on" | "off"required
  • notestring | nullrequired
  • updated_atstring | nullrequired
  • countriesobject[]required

    Each country the company employs people in (or has a location in): its law and whether quiet hours apply.

    8 fields
    • countrystringrequired
    • lawstringrequired
    • source_urlstringrequired
    • min_peopleinteger | nullrequired
    • notestringrequired
    • peopleintegerrequired

      Active people employed by legal entities in this country.

    • requiredbooleanrequired

      The law requires quiet hours here (they stay on whatever the mode).

    • appliesbooleanrequired
  • checked_onstringrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/country/disconnect.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "mode": "law",
    "note": null,
    "updated_at": null,
    "checked_on": "2026-11-14",
    "countries": [
      {
        "country": "PT",
        "law": "Código do Trabalho, art. 199.º-A (Lei n.º 83/2021)",
        "source_url": "https://diariodarepublica.pt/dr/detalhe/lei/83-2021-175397114",
        "min_people": 0,
        "note": "The employer must refrain from contacting workers in their rest period.",
        "people": 12,
        "required": true,
        "applies": true
      }
    ]
  }
}

Change the right to disconnect policy#

POST/v1/country/disconnect.updateWrite

Sets the mode (law, on, off) and/or the policy text people see in Me (at most 4000 characters; null removes it). "off" never switches off quiet hours where the law requires them (PT, ES; FR from 50 and BE from 20 people per employer): the result says where they stay on. Owners and admins.

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

  • mode"law" | "on" | "off"
  • notestring | null

    Up to 4000 characters.

Returns

  • mode"law" | "on" | "off"required
  • notestring | nullrequired
  • updated_atstring | nullrequired
  • countriesobject[]required

    Each country the company employs people in (or has a location in): its law and whether quiet hours apply.

    8 fields
    • countrystringrequired
    • lawstringrequired
    • source_urlstringrequired
    • min_peopleinteger | nullrequired
    • notestringrequired
    • peopleintegerrequired

      Active people employed by legal entities in this country.

    • requiredbooleanrequired

      The law requires quiet hours here (they stay on whatever the mode).

    • appliesbooleanrequired
  • checked_onstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl
curl https://api.bizisy.com/v1/country/disconnect.update \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"note":"We do not expect answers outside working hours."}'
Response
{
  "data": {
    "mode": "law",
    "note": "We do not expect answers outside working hours.",
    "updated_at": null,
    "checked_on": "2026-11-14",
    "countries": [
      {
        "country": "PT",
        "law": "Código do Trabalho, art. 199.º-A (Lei n.º 83/2021)",
        "source_url": "https://diariodarepublica.pt/dr/detalhe/lei/83-2021-175397114",
        "min_people": 0,
        "note": "The employer must refrain from contacting workers in their rest period.",
        "people": 12,
        "required": true,
        "applies": true
      }
    ]
  }
}

My quiet hours#

POST/v1/country/disconnect.mineRead

Your quiet hours: whether your company holds non-urgent emails and push notifications outside your working time, your next working periods (from your work schedule and published shifts, in your time zone), whether you are in quiet hours now and when held notices reach you, and your company's policy text. Sign-in and security notices, decisions on your own requests and urgent announcements are never held. Everyone with a person record.

Who can call it
Me key anyone
MCP tool
country_disconnect_mine on My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

8 fields
  • appliesbooleanrequired
  • quiet_nowbooleanrequired
  • next_deliverystring | nullrequired

    When held notices go out (null: not in quiet hours).

  • time_zonestring | nullrequired
  • periodsobject[]required

    Your working periods in the next 7 days.

    2 fields
    • startstringrequired
    • endstringrequired
  • notestring | nullrequired
  • lawstring | nullrequired
  • source_urlstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/country/disconnect.mine \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "data": {
    "applies": true,
    "quiet_now": true,
    "next_delivery": "2026-10-12T08:00:00.000Z",
    "time_zone": "Europe/Lisbon",
    "periods": [
      {
        "start": "2026-10-12T08:00:00.000Z",
        "end": "2026-10-12T17:00:00.000Z"
      }
    ],
    "note": "We do not expect answers outside working hours.",
    "law": "Código do Trabalho, art. 199.º-A (Lei n.º 83/2021)",
    "source_url": "https://diariodarepublica.pt/dr/detalhe/lei/83-2021-175397114"
  }
}

When people receive notices#

POST/v1/country/disconnect.whenRead

For up to 50 people you manage (or anyone, for owners, admins and HR): whether they are outside their working time now and, if so, when a non-urgent email or push you cause reaches them ("will be delivered at 09:00"). People you can't see are left out. Nothing about why they are off.

Who can call it
Manage key any Manage role
Me key anyone
MCP tool
country_disconnect_when on My Workplace, HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • person_idsstring[]required

    1–64 characters. 1–50 items.

Returns

  • peopleobject[]required
    4 fields
    • person_idstringrequired
    • quietbooleanrequired
    • deliver_atstring | nullrequired
    • time_zonestringrequired

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl
curl https://api.bizisy.com/v1/country/disconnect.when \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"person_ids":["p1","p2"]}'
Response
{
  "data": {
    "people": [
      {
        "person_id": "p1",
        "quiet": true,
        "deliver_at": "2026-10-12T08:00:00.000Z",
        "time_zone": "Europe/Lisbon"
      }
    ]
  }
}

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

Developer docs