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_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
entitiesobject[]required5 fields
legal_entityobjectrequired4 fields
idstringrequirednamestringrequiredcountrystringrequiredarchivedbooleanrequired
rulesobject | nullrequirednull: Bizisy has no rules for this country (outside the EU and EEA).
4 fields
countrystring | nullrequiredThe country whose own rules apply; null: the EU default.
sourcestringrequiredchecked_onstringrequirednotestring | nullrequired
obligationsobject[]required12 fields
idstringrequiredkindstring (enum)requiredOne of:
hire_notice,leave_notice,staff_report,written_terms,vacation_plan,pay_notice,payroll_declaration,training_hours,schedule_map.authoritystringrequiredlawstringrequiredsource_urlstringrequireddeadlineobjectrequired8 fields
kindstringrequireddaysintegeropens_daysintegerdayintegerfromstringtostringbystringuntilstring
channel"webservice" | "file" | "sheet" | "info" | "post"requiredwebservice: 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"requiredHow 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.
openintegerrequiredNotices or reports of this obligation that need someone now (due, overdue or refused).
notestring | nullrequiredannexesobject[]requiredYearly reports with annexes: what Bizisy fills of each (full, partial, out) and why.
4 fields
idstringrequirednamestringrequiredscope"full" | "partial" | "out"requiredwhystringrequired
fromstring | nullrequiredThe rule applies to events from this day (e.g. Portugal's pay-change notices from 2027).
missingintegerrequiredCountry data values these obligations need that are not entered yet (company data: legal entity, locations, job titles).
payrollstring[]requiredPayroll exports or connectors that fit this country (ids).
segsocialobjectrequired2 fields
availablebooleanrequiredenvironment"production" | "quality"required
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/country/obligations.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/country/obligations.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/country/obligations.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
openbooleanOnly those that need someone now (due, overdue, failed).
person_idstring1–100 characters.
legal_entity_idstring1–100 characters.
Returns
as_ofstringrequirednoticesobject[]required15 fields
keystringrequiredStable notice key (obligation:subject:date) for country_notices_record and the app.
obligationstringrequiredcountrystringrequiredkindstring (enum)requiredOne 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"requiredauthoritystringrequiredpersonobject | nullrequired2 fields
idstringrequirednamestringrequired
legal_entityobjectrequired2 fields
idstringrequirednamestringrequired
event"hire" | "leave" | "report" | "pay"requiredevent_datestringrequiredThe first day (hire), the last day (leave), the day base pay changed (pay; listed in the app only) or the year (report).
opens_onstringrequiredFrom when it can be made.
due_onstringrequiredIts last day.
state"upcoming" | "due" | "overdue" | "failed" | "sent" | "skipped"requiredupcoming (not yet), due, overdue, failed (the authority refused it), sent, skipped (not needed).
currentbooleanrequiredFalse for a record about a date Bizisy no longer has (the start or last day was corrected).
recordobject | nullrequired7 fields
status"sent" | "failed" | "skipped"requiredchannel"webservice" | "manual"requiredreferencestring | nullrequiredsent_onstring | nullrequiredreasonstring | nullrequirederrorobject | nullrequired3 fields
code"refused" | "auth" | "unavailable" | "invalid"requiredmessagestringrequiredofficialstring | nullrequiredThe 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 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"}'const res = await fetch('https://api.bizisy.com/v1/country/notices.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"person_id": "p1",
"legal_entity_id": "le1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/country/notices.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"person_id": "p1",
"legal_entity_id": "le1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_prepareon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
keystringrequired5–160 characters.
choicesobject8 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_basenumberPT 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 | 1PT leave: reported for unemployment benefit (default 1; Segurança Social records it either way).
fundamentacaostringPT 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
noticeobjectrequired15 fields
keystringrequiredStable notice key (obligation:subject:date) for country_notices_record and the app.
obligationstringrequiredcountrystringrequiredkindstring (enum)requiredOne 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"requiredauthoritystringrequiredpersonobject | nullrequired2 fields
idstringrequirednamestringrequired
legal_entityobjectrequired2 fields
idstringrequirednamestringrequired
event"hire" | "leave" | "report" | "pay"requiredevent_datestringrequiredThe first day (hire), the last day (leave), the day base pay changed (pay; listed in the app only) or the year (report).
opens_onstringrequiredFrom when it can be made.
due_onstringrequiredIts last day.
state"upcoming" | "due" | "overdue" | "failed" | "sent" | "skipped"requiredupcoming (not yet), due, overdue, failed (the authority refused it), sent, skipped (not needed).
currentbooleanrequiredFalse for a record about a date Bizisy no longer has (the start or last day was corrected).
recordobject | nullrequired7 fields
status"sent" | "failed" | "skipped"requiredchannel"webservice" | "manual"requiredreferencestring | nullrequiredsent_onstring | nullrequiredreasonstring | nullrequirederrorobject | nullrequired3 fields
code"refused" | "auth" | "unavailable" | "invalid"requiredmessagestringrequiredofficialstring | nullrequiredThe authority's own message, only when it is one of its documented ones.
attemptsintegerrequired
how"send" | "manual" | "file" | "sheet" | "info" | "post"requiredmissingobject[]required3 fields
keystringrequiredsubjectstring (enum)requiredOne of:
person,job,pay,entity,location,title,choice.subject_idstring | nullrequired
warningsstring[]requiredpayloadobject | nullrequiredchoicesobjectrequiredsheetobject[]required2 fields
keystringrequiredvaluestring | nullrequired
fileobject | nullrequired3 fields
filenamestringrequiredcontent_base64stringrequiredcontent_typestringrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
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
}
}'const res = await fetch('https://api.bizisy.com/v1/country/notices.prepare', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"key": "pt.leave:p1:2026-09-30",
"choices": {
"motivo_fim": "IIDD",
"comunicacao_desemprego": 1
}
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/country/notices.prepare",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"key": "pt.leave:p1:2026-09-30",
"choices": {
"motivo_fim": "IIDD",
"comunicacao_desemprego": 1,
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_submiton HR Assistant- Preview
?dry_run=trueruns 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
keystringrequired5–160 characters.
choicesobject8 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_basenumberPT 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 | 1PT leave: reported for unemployment benefit (default 1; Segurança Social records it either way).
fundamentacaostringPT 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"requiredpayloadobjectrequirederrorobject | nullrequired3 fields
code"refused" | "auth" | "unavailable" | "invalid"requiredmessagestringrequiredofficialstring | nullrequiredThe 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 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"
}
}'const res = await fetch('https://api.bizisy.com/v1/country/notices.submit', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"key": "pt.hire:p1:2026-10-20",
"choices": {
"modalidade": "E",
"motivo_contrato": "ATSA",
"prestacao": "P"
}
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/country/notices.submit",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"key": "pt.hire:p1:2026-10-20",
"choices": {
"modalidade": "E",
"motivo_contrato": "ATSA",
"prestacao": "P",
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_recordon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
itemsobject[]required1–200 items.
5 fields
keystringrequired5–160 characters.
status"sent" | "skipped"requiredsent: it was made (outside Bizisy, e.g. in Segurança Social Direta or by your gestoría); skipped: not needed.
referencestringsent: the receipt number, when there is one.
Up to 60 characters. Pattern
^[\w ./-]*$.sent_onstringsent: 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 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"
}
]
}'const res = await fetch('https://api.bizisy.com/v1/country/notices.record', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"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"
}
]
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/country/notices.record",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"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",
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_reopenon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
keystringrequired5–160 characters.
Returns
reopenedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/country/notices.reopen', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"key": "pt.hire:p1:2026-10-20"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/country/notices.reopen",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"key": "pt.hire:p1:2026-10-20",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
subject"entity" | "location" | "title" | "person"
Returns
fieldsobject[]required8 fields
keystringrequiredsubject"entity" | "location" | "title" | "person"requiredlabelstringrequiredhelpstringrequiredpatternstringrequiredtier"company" | "private"requireddefaultstring | nullrequiredcountriesstring[]required
subjectsobject[]required8 fields
subject"entity" | "location" | "title" | "person"requiredidstringrequirednamestringrequiredcountrystring | nullrequiredvaluesobjectrequiredfieldsstring[]requiredThe keys this subject takes (from its countries' rules).
missingstring[]requiredKeys with no value and no default.
suggestionsobject[]requiredPeople 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
keystringrequiredcodestringrequiredfromobjectrequired3 fields
qualificationstringrequiredisced_levelintegerrequiredisced_fieldstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/country/facts.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"subject":"title"}'const res = await fetch('https://api.bizisy.com/v1/country/facts.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"subject": "title"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/country/facts.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"subject": "title",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_seton HR Assistant- Preview
?dry_run=trueruns 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"requiredsubject_idstringrequired1–100 characters.
valuesobjectrequired
Returns
valuesobjectrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
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
}
}'const res = await fetch('https://api.bizisy.com/v1/country/facts.set', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"subject": "title",
"subject_id": "t1",
"values": {
"pt_cpp": "25121",
"pt_nivel_qual": null
}
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/country/facts.set",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"subject": "title",
"subject_id": "t1",
"values": {
"pt_cpp": "25121",
"pt_nivel_qual": None,
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
availablebooleanrequiredenvironment"production" | "quality"requiredentitiesobject[]required2 fields
legal_entityobjectrequired2 fields
idstringrequirednamestringrequired
credentialsobject | nullrequired4 fields
usernamestringrequiredstatus"unchecked" | "working" | "refused"requiredchecked_atstring | nullrequiredset_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/country/credentials.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/country/credentials.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/country/credentials.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_seton HR Assistant- Preview
?dry_run=trueruns 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_idstringrequired1–100 characters.
usernamestringrequired3–40 characters. Pattern
^[\w.@-]+$.passwordstringrequired1–200 characters.
Returns
legal_entity_idstringrequiredusernamestringrequiredstatus"unchecked"required
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
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"
}'const res = await fetch('https://api.bizisy.com/v1/country/credentials.set', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"legal_entity_id": "le1",
"username": "20000000001",
"password": "app-password"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/country/credentials.set",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"legal_entity_id": "le1",
"username": "20000000001",
"password": "app-password",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_clearon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
legal_entity_idstringrequired1–100 characters.
Returns
removedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/country/credentials.clear', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"legal_entity_id": "le1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/country/credentials.clear",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"legal_entity_id": "le1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_readinesson HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
yearintegerFrom 2010 to 2100.
legal_entity_idstring1–100 characters.
Returns
as_ofstringrequiredyearintegerrequiredentitiesobject[]required13 fields
legal_entityobjectrequired2 fields
idstringrequirednamestringrequired
yearintegerrequiredopens_onstringrequiredThe legal window (Portaria 55/2010 art. 4.º: 16 March); it has been moved by notice in recent years.
due_onstringrequiredstate"preparing" | "due" | "overdue" | "sent" | "skipped"requiredreadybooleanrequiredNothing required is missing for Anexos A and B (the gaps of Anexos 0, C, D and F are listed in missing with their annex).
workersintegerrequiredPeople in Anexo A (employed at some point in October).
movementsintegerrequiredPeople in Anexo B (started and/or left in the year).
missing_totalintegerrequiredmissingobject[]required5 fields
keystringrequiredWhat 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)requiredOne of:
person,job,pay,entity,location,title,choice,course,training_record,report.annexes"0" | "A" | "B" | "C" | "D" | "F"[]requiredcountintegerrequireditemsobject[]requiredThe records to fix, with names; empty over API keys and AI connections (counts only).
2 fields
idstring | nullrequirednamestring | nullrequired
warningsstring[]requiredhistoryobject[]required8 fields
idstringrequiredyearintegerrequiredannexesstring (enum)[]requiredOne of:
0,A,B,C,D,E,F.workersintegerrequiredmovementsintegerrequiredmissingintegerrequiredby_firmstring | nullrequiredcreated_atstringrequired
sentobject | nullrequired2 fields
sent_onstring | nullrequiredreferencestring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/country/relatorio_unico.readiness', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"year": 2025,
"legal_entity_id": "le1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/country/relatorio_unico.readiness",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"year": 2025,
"legal_entity_id": "le1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_generateon HR Assistant- Preview
?dry_run=trueruns 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_idstringrequired1–100 characters.
yearintegerrequiredFrom 2010 to 2100.
no_strikesbooleanYou confirm there were no strikes in the year: Bizisy adds Anexo E's "no strikes" file.
Returns
9 fields
readybooleanrequiredworkersintegerrequiredheadcount_31_octoberintegerrequiredestablishmentsintegerrequiredmovementsintegerrequiredmissingobject[]required4 fields
keystringrequiredsubjectstring (enum)requiredOne of:
person,job,pay,entity,location,title,choice,course,training_record,report.subject_idstring | nullrequiredannexes"0" | "A" | "B" | "C" | "D" | "F"[]required
warningsstring[]requiredfilesobject[]required4 fields
annexstring (enum)requiredOne of:
0,A,B,C,D,E,F.filenamestringrequiredcontent_base64stringrequiredcontent_typestringrequired
summaryobjectrequired19 fields
yearintegerrequiredentitystringrequiredheadcount_31_octoberintegerrequiredheadcount_31_decemberintegerrequiredaverage_headcountnumberrequiredestablishmentsobject[]required4 fields
idstring | nullrequirednamestringrequiredhead_officebooleanrequiredpeople_31_octoberintegerrequired
by_sexobjectrequiredby_contractobjectrequiredBy RU table 13 code.
by_qualificationobjectrequiredBy RU table 21 level.
by_ageobjectrequiredby_educationobjectrequiredBy the first digit of RU table 14.
full_timeintegerrequiredpart_timeintegerrequiredpayobject | nullrequiredOctober monthly base pay in EUR; null with fewer than 3 people.
3 fields
lowestnumberrequiredmediannumberrequiredhighestnumberrequired
entriesintegerrequiredexitsintegerrequiredexits_by_reasonobjectrequiredBy RU table 27 code.
contractorsintegerrequiredannexesobject[]required2 fields
idstringrequiredstatus"made" | "missing_data" | "figures" | "not_asked" | "out"required
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
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}'const res = await fetch('https://api.bizisy.com/v1/country/relatorio_unico.generate', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"legal_entity_id": "le1",
"year": 2025,
"no_strikes": true
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/country/relatorio_unico.generate",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"legal_entity_id": "le1",
"year": 2025,
"no_strikes": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
legal_entity_idstringrequired1–100 characters.
yearintegerFrom 2010 to 2100.
Returns
8 fields
legal_entityobjectrequired2 fields
idstringrequirednamestringrequired
yearintegerrequiredzeroobject | nullrequiredAnexo 0's form; null until saved.
19 fields
turnoverinteger | nullrequiredVIII-1 volume de negócios: the year's turnover in whole euros.
From 0 to 999999999999.
turnover_yearinteger | nullrequiredThe year the turnover refers to (default: the report's year).
From 2000 to 2100.
union_membersinteger | nullrequiredIV-1 workers in a trade union on 31 October (a count; Bizisy keeps no membership).
From 0 to 99999.
posted_workersintegerrequiredIII-2.1 workers posted abroad in the year.
From 0 to 99999.
postingsintegerrequiredIII-2.2 number of postings (0 with no posted workers).
From 0 to 99999.
associationsstring[]requiredIV-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"requiredV-1 was overtime worked in the year (S/N)?
overtime_list_endorsed"S" | "N"requiredV-2 with overtime: was the nominal list of who worked it (art. 227.º) endorsed by the workers' committee or union (S/N)?
others_31_decintegerrequiredPeople 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 | nullrequiredFrom 0 to 99999.
temp_31_decinteger | nullrequiredFrom 0 to 99999.
temp_averageinteger | nullrequiredVI-1 temporary agency workers used: on 31 October, 31 December and the yearly average.
From 0 to 99999.
capitalinteger | nullrequiredVIII-2 share capital in euros.
From 0 to 999999999999.
capital_private_ptnumber | nullrequiredFrom 0 to 100.
capital_foreignnumber | nullrequiredFrom 0 to 100.
capital_public_ptnumber | nullrequiredFrom 0 to 100.
spendingobjectrequiredOptional 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_formintegerFrom 0 to 999999999999.
rest_finan_entintegerFrom 0 to 999999999999.
finan_fseintegerFrom 0 to 999999999999.
finan_outras_fontesintegerFrom 0 to 999999999999.
encarg_org_sstintegerFrom 0 to 999999999999.
encarg_org_esp_trabintegerFrom 0 to 999999999999.
encarg_aqui_bensintegerFrom 0 to 999999999999.
encarg_formintegerFrom 0 to 999999999999.
encarg_outrosintegerFrom 0 to 999999999999.
accountsobjectrequiredIX-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
vabintegerFrom -9999999999 to 9999999999.
custos_pessoalintegerFrom -9999999999 to 9999999999.
amort_exercintegerFrom -9999999999 to 9999999999.
provi_exercintegerFrom -9999999999 to 9999999999.
custos_perdasintegerFrom -9999999999 to 9999999999.
impost_rendintegerFrom -9999999999 to 9999999999.
res_liquidointegerFrom -9999999999 to 9999999999.
sstobject | nullrequiredAnexo 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"requiredII-1 were safety-at-work services organised?
health"S" | "N"requiredII-2 were health-at-work services organised?
together"C" | "S"requiredII-4 with both: organised together (C) or separately (S).
safety_modes"internal" | "common" | "external" | "employer" | "designated"[]requiredII-5.1 internal, common (serviço comum), external, employer, designated (trabalhador designado).
Up to 5 items.
health_modes"internal" | "common" | "external" | "sns"[]requiredII-5.2 internal, common, external, sns (Serviço Nacional/Regional de Saúde).
Up to 4 items.
complemented"S" | "N"requiredII-6 were the services complemented?
first_aid_workersintegerrequiredII-3 workers in first aid, firefighting and evacuation (per establishment unless overridden).
From 0 to 999.
nursesintegerrequiredFrom 0 to 99.
other_staffintegerrequiredFrom 0 to 99.
doctorsobject[]requiredIII-1.2 occupational doctors: name, cédula profissional, monthly hours (HHH,MM).
Up to 20 items.
3 fields
namestringrequired1–70 characters.
licencestringrequiredPattern
^\d{1,5}$.monthly_hoursstringrequiredPattern
^\d{1,3},\d{2}$.
techniciansobject[]requiredIII-1.3 safety technicians (senior: técnico superior) with their CAP number.
Up to 20 items.
3 fields
namestringrequired1–70 characters.
capstringrequired3–40 characters.
seniorbooleanrequired
safety_headobject | nullrequired2 fields
nifstringrequiredPattern
^\d{9}$.namestringrequired1–70 characters.
health_headobject | nullrequired2 fields
nifstringrequiredPattern
^\d{9}$.namestringrequired1–70 characters.
employerobject | nullrequired2 fields
namestringrequired1–70 characters.
authorizationstringrequiredPattern
^\d{1,8}$.
designatedobject | nullrequired2 fields
namestringrequired1–70 characters.
authorizationstringrequiredPattern
^\d{1,8}$.
representativestring | nullrequired1–70 characters.
safety_servicesobject[]requiredUp to 20 items.
3 fields
nifstringrequiredPattern
^\d{9}$.namestring | nullrequired1–100 characters.
type"1" | "2" | "3" | "4"requiredRelatório Único table 37: 1 associativo, 2 cooperativo, 3 convencionado, 4 privado.
health_servicesobject[]requiredUp to 20 items.
3 fields
nifstringrequiredPattern
^\d{9}$.namestring | nullrequired1–100 characters.
type"1" | "2" | "3" | "4"requiredRelatório Único table 37: 1 associativo, 2 cooperativo, 3 convencionado, 4 privado.
prevention"S" | "N"requiredpromotion"S" | "N"requiredsurveillance"S" | "N"requiredaudits"S" | "N"requiredinspections"S" | "N"requiredinformation"S" | "N"requiredconsultation"S" | "N"requiredtraining"S" | "N"requiredrisksobjectrequired6 fields
physical"S" | "N"requiredchemical"S" | "N"requiredbiological"S" | "N"requiredmusculoskeletal"S" | "N"requiredpsychosocial"S" | "N"requiredother"S" | "N"required
exams"S" | "N"requiredcomplementary_exams"S" | "N"requiredimmunisation"S" | "N"requiredhealth_promotion"S" | "N"requireddiseases_reported"S" | "N"requireddiseases_confirmed"S" | "N"requiredno_accidentsbooleanrequiredNo leave type is marked as a work accident and there were none: confirm it (else Bizisy can't count them).
establishmentsobject[]requiredPer 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_idstringrequired1–100 characters.
hours_workedinteger | nullrequiredFrom 0 to 999999999.
first_aid_workersinteger | nullrequiredFrom 0 to 999.
no_leaveobjectrequired2 fields
hintegerrequiredFrom 0 to 9999.
mintegerrequiredFrom 0 to 9999.
fatalobjectrequired2 fields
hintegerrequiredFrom 0 to 9999.
mintegerrequiredFrom 0 to 9999.
othersobjectrequired2 fields
hintegerrequiredFrom 0 to 9999.
mintegerrequiredFrom 0 to 9999.
providers_nonebooleanrequiredAnexo F: confirmed there were no service providers in the year.
providersintegerrequiredService providers listed for the year.
prefillobjectrequired6 fields
employees_31_decemberintegerrequiredemployees_averageintegerrequiredheadcount_31_octoberintegerrequiredWith 10 or more, Anexo 0 asks for section IX (accounts).
timeoffbooleanrequiredTime off is on: accidents are counted from it.
accident_typesintegerrequiredLeave types marked as work accidents (0: Bizisy can't count accidents).
establishmentsobject[]required8 fields
location_idstring | nullrequirednamestring | nullrequiredru_estabstring | nullrequiredemployeesintegerrequiredYearly average of employees.
contractorsintegerrequiredhours_estimateintegerrequiredEstimated hours worked (weekdays × weekly hours ÷ 5, less vacation, public holidays and work-accident days).
accidentsinteger | nullrequiredWork 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 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}'const res = await fetch('https://api.bizisy.com/v1/country/relatorio_unico.annual.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"legal_entity_id": "le1",
"year": 2025
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/country/relatorio_unico.annual.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"legal_entity_id": "le1",
"year": 2025,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_seton HR Assistant- Preview
?dry_run=trueruns 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_idstringrequired1–100 characters.
yearintegerrequiredFrom 2010 to 2100.
zeroobject | null19 fields
turnoverinteger | nullrequiredVIII-1 volume de negócios: the year's turnover in whole euros.
From 0 to 999999999999.
turnover_yearinteger | nullrequiredThe year the turnover refers to (default: the report's year).
From 2000 to 2100.
union_membersinteger | nullrequiredIV-1 workers in a trade union on 31 October (a count; Bizisy keeps no membership).
From 0 to 99999.
posted_workersintegerrequiredIII-2.1 workers posted abroad in the year.
From 0 to 99999.
postingsintegerrequiredIII-2.2 number of postings (0 with no posted workers).
From 0 to 99999.
associationsstring[]requiredIV-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"requiredV-1 was overtime worked in the year (S/N)?
overtime_list_endorsed"S" | "N"requiredV-2 with overtime: was the nominal list of who worked it (art. 227.º) endorsed by the workers' committee or union (S/N)?
others_31_decintegerrequiredPeople 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 | nullrequiredFrom 0 to 99999.
temp_31_decinteger | nullrequiredFrom 0 to 99999.
temp_averageinteger | nullrequiredVI-1 temporary agency workers used: on 31 October, 31 December and the yearly average.
From 0 to 99999.
capitalinteger | nullrequiredVIII-2 share capital in euros.
From 0 to 999999999999.
capital_private_ptnumber | nullrequiredFrom 0 to 100.
capital_foreignnumber | nullrequiredFrom 0 to 100.
capital_public_ptnumber | nullrequiredFrom 0 to 100.
spendingobjectrequiredOptional 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_formintegerFrom 0 to 999999999999.
rest_finan_entintegerFrom 0 to 999999999999.
finan_fseintegerFrom 0 to 999999999999.
finan_outras_fontesintegerFrom 0 to 999999999999.
encarg_org_sstintegerFrom 0 to 999999999999.
encarg_org_esp_trabintegerFrom 0 to 999999999999.
encarg_aqui_bensintegerFrom 0 to 999999999999.
encarg_formintegerFrom 0 to 999999999999.
encarg_outrosintegerFrom 0 to 999999999999.
accountsobjectrequiredIX-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
vabintegerFrom -9999999999 to 9999999999.
custos_pessoalintegerFrom -9999999999 to 9999999999.
amort_exercintegerFrom -9999999999 to 9999999999.
provi_exercintegerFrom -9999999999 to 9999999999.
custos_perdasintegerFrom -9999999999 to 9999999999.
impost_rendintegerFrom -9999999999 to 9999999999.
res_liquidointegerFrom -9999999999 to 9999999999.
sstobject | null35 fields
safety"S" | "N"requiredII-1 were safety-at-work services organised?
health"S" | "N"requiredII-2 were health-at-work services organised?
together"C" | "S"requiredII-4 with both: organised together (C) or separately (S).
safety_modes"internal" | "common" | "external" | "employer" | "designated"[]requiredII-5.1 internal, common (serviço comum), external, employer, designated (trabalhador designado).
Up to 5 items.
health_modes"internal" | "common" | "external" | "sns"[]requiredII-5.2 internal, common, external, sns (Serviço Nacional/Regional de Saúde).
Up to 4 items.
complemented"S" | "N"requiredII-6 were the services complemented?
first_aid_workersintegerrequiredII-3 workers in first aid, firefighting and evacuation (per establishment unless overridden).
From 0 to 999.
nursesintegerrequiredFrom 0 to 99.
other_staffintegerrequiredFrom 0 to 99.
doctorsobject[]requiredIII-1.2 occupational doctors: name, cédula profissional, monthly hours (HHH,MM).
Up to 20 items.
3 fields
namestringrequired1–70 characters.
licencestringrequiredPattern
^\d{1,5}$.monthly_hoursstringrequiredPattern
^\d{1,3},\d{2}$.
techniciansobject[]requiredIII-1.3 safety technicians (senior: técnico superior) with their CAP number.
Up to 20 items.
3 fields
namestringrequired1–70 characters.
capstringrequired3–40 characters.
seniorbooleanrequired
safety_headobject | nullrequired2 fields
nifstringrequiredPattern
^\d{9}$.namestringrequired1–70 characters.
health_headobject | nullrequired2 fields
nifstringrequiredPattern
^\d{9}$.namestringrequired1–70 characters.
employerobject | nullrequired2 fields
namestringrequired1–70 characters.
authorizationstringrequiredPattern
^\d{1,8}$.
designatedobject | nullrequired2 fields
namestringrequired1–70 characters.
authorizationstringrequiredPattern
^\d{1,8}$.
representativestring | nullrequired1–70 characters.
safety_servicesobject[]requiredUp to 20 items.
3 fields
nifstringrequiredPattern
^\d{9}$.namestring | nullrequired1–100 characters.
type"1" | "2" | "3" | "4"requiredRelatório Único table 37: 1 associativo, 2 cooperativo, 3 convencionado, 4 privado.
health_servicesobject[]requiredUp to 20 items.
3 fields
nifstringrequiredPattern
^\d{9}$.namestring | nullrequired1–100 characters.
type"1" | "2" | "3" | "4"requiredRelatório Único table 37: 1 associativo, 2 cooperativo, 3 convencionado, 4 privado.
prevention"S" | "N"requiredpromotion"S" | "N"requiredsurveillance"S" | "N"requiredaudits"S" | "N"requiredinspections"S" | "N"requiredinformation"S" | "N"requiredconsultation"S" | "N"requiredtraining"S" | "N"requiredrisksobjectrequired6 fields
physical"S" | "N"requiredchemical"S" | "N"requiredbiological"S" | "N"requiredmusculoskeletal"S" | "N"requiredpsychosocial"S" | "N"requiredother"S" | "N"required
exams"S" | "N"requiredcomplementary_exams"S" | "N"requiredimmunisation"S" | "N"requiredhealth_promotion"S" | "N"requireddiseases_reported"S" | "N"requireddiseases_confirmed"S" | "N"requiredno_accidentsbooleanrequiredNo leave type is marked as a work accident and there were none: confirm it (else Bizisy can't count them).
establishmentsobject[]requiredPer 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_idstringrequired1–100 characters.
hours_workedinteger | nullrequiredFrom 0 to 999999999.
first_aid_workersinteger | nullrequiredFrom 0 to 999.
no_leaveobjectrequired2 fields
hintegerrequiredFrom 0 to 9999.
mintegerrequiredFrom 0 to 9999.
fatalobjectrequired2 fields
hintegerrequiredFrom 0 to 9999.
mintegerrequiredFrom 0 to 9999.
othersobjectrequired2 fields
hintegerrequiredFrom 0 to 9999.
mintegerrequiredFrom 0 to 9999.
providers_noneboolean
Returns
8 fields
legal_entityobjectrequired2 fields
idstringrequirednamestringrequired
yearintegerrequiredzeroobject | nullrequiredAnexo 0's form; null until saved.
19 fields
turnoverinteger | nullrequiredVIII-1 volume de negócios: the year's turnover in whole euros.
From 0 to 999999999999.
turnover_yearinteger | nullrequiredThe year the turnover refers to (default: the report's year).
From 2000 to 2100.
union_membersinteger | nullrequiredIV-1 workers in a trade union on 31 October (a count; Bizisy keeps no membership).
From 0 to 99999.
posted_workersintegerrequiredIII-2.1 workers posted abroad in the year.
From 0 to 99999.
postingsintegerrequiredIII-2.2 number of postings (0 with no posted workers).
From 0 to 99999.
associationsstring[]requiredIV-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"requiredV-1 was overtime worked in the year (S/N)?
overtime_list_endorsed"S" | "N"requiredV-2 with overtime: was the nominal list of who worked it (art. 227.º) endorsed by the workers' committee or union (S/N)?
others_31_decintegerrequiredPeople 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 | nullrequiredFrom 0 to 99999.
temp_31_decinteger | nullrequiredFrom 0 to 99999.
temp_averageinteger | nullrequiredVI-1 temporary agency workers used: on 31 October, 31 December and the yearly average.
From 0 to 99999.
capitalinteger | nullrequiredVIII-2 share capital in euros.
From 0 to 999999999999.
capital_private_ptnumber | nullrequiredFrom 0 to 100.
capital_foreignnumber | nullrequiredFrom 0 to 100.
capital_public_ptnumber | nullrequiredFrom 0 to 100.
spendingobjectrequiredOptional 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_formintegerFrom 0 to 999999999999.
rest_finan_entintegerFrom 0 to 999999999999.
finan_fseintegerFrom 0 to 999999999999.
finan_outras_fontesintegerFrom 0 to 999999999999.
encarg_org_sstintegerFrom 0 to 999999999999.
encarg_org_esp_trabintegerFrom 0 to 999999999999.
encarg_aqui_bensintegerFrom 0 to 999999999999.
encarg_formintegerFrom 0 to 999999999999.
encarg_outrosintegerFrom 0 to 999999999999.
accountsobjectrequiredIX-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
vabintegerFrom -9999999999 to 9999999999.
custos_pessoalintegerFrom -9999999999 to 9999999999.
amort_exercintegerFrom -9999999999 to 9999999999.
provi_exercintegerFrom -9999999999 to 9999999999.
custos_perdasintegerFrom -9999999999 to 9999999999.
impost_rendintegerFrom -9999999999 to 9999999999.
res_liquidointegerFrom -9999999999 to 9999999999.
sstobject | nullrequiredAnexo 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"requiredII-1 were safety-at-work services organised?
health"S" | "N"requiredII-2 were health-at-work services organised?
together"C" | "S"requiredII-4 with both: organised together (C) or separately (S).
safety_modes"internal" | "common" | "external" | "employer" | "designated"[]requiredII-5.1 internal, common (serviço comum), external, employer, designated (trabalhador designado).
Up to 5 items.
health_modes"internal" | "common" | "external" | "sns"[]requiredII-5.2 internal, common, external, sns (Serviço Nacional/Regional de Saúde).
Up to 4 items.
complemented"S" | "N"requiredII-6 were the services complemented?
first_aid_workersintegerrequiredII-3 workers in first aid, firefighting and evacuation (per establishment unless overridden).
From 0 to 999.
nursesintegerrequiredFrom 0 to 99.
other_staffintegerrequiredFrom 0 to 99.
doctorsobject[]requiredIII-1.2 occupational doctors: name, cédula profissional, monthly hours (HHH,MM).
Up to 20 items.
3 fields
namestringrequired1–70 characters.
licencestringrequiredPattern
^\d{1,5}$.monthly_hoursstringrequiredPattern
^\d{1,3},\d{2}$.
techniciansobject[]requiredIII-1.3 safety technicians (senior: técnico superior) with their CAP number.
Up to 20 items.
3 fields
namestringrequired1–70 characters.
capstringrequired3–40 characters.
seniorbooleanrequired
safety_headobject | nullrequired2 fields
nifstringrequiredPattern
^\d{9}$.namestringrequired1–70 characters.
health_headobject | nullrequired2 fields
nifstringrequiredPattern
^\d{9}$.namestringrequired1–70 characters.
employerobject | nullrequired2 fields
namestringrequired1–70 characters.
authorizationstringrequiredPattern
^\d{1,8}$.
designatedobject | nullrequired2 fields
namestringrequired1–70 characters.
authorizationstringrequiredPattern
^\d{1,8}$.
representativestring | nullrequired1–70 characters.
safety_servicesobject[]requiredUp to 20 items.
3 fields
nifstringrequiredPattern
^\d{9}$.namestring | nullrequired1–100 characters.
type"1" | "2" | "3" | "4"requiredRelatório Único table 37: 1 associativo, 2 cooperativo, 3 convencionado, 4 privado.
health_servicesobject[]requiredUp to 20 items.
3 fields
nifstringrequiredPattern
^\d{9}$.namestring | nullrequired1–100 characters.
type"1" | "2" | "3" | "4"requiredRelatório Único table 37: 1 associativo, 2 cooperativo, 3 convencionado, 4 privado.
prevention"S" | "N"requiredpromotion"S" | "N"requiredsurveillance"S" | "N"requiredaudits"S" | "N"requiredinspections"S" | "N"requiredinformation"S" | "N"requiredconsultation"S" | "N"requiredtraining"S" | "N"requiredrisksobjectrequired6 fields
physical"S" | "N"requiredchemical"S" | "N"requiredbiological"S" | "N"requiredmusculoskeletal"S" | "N"requiredpsychosocial"S" | "N"requiredother"S" | "N"required
exams"S" | "N"requiredcomplementary_exams"S" | "N"requiredimmunisation"S" | "N"requiredhealth_promotion"S" | "N"requireddiseases_reported"S" | "N"requireddiseases_confirmed"S" | "N"requiredno_accidentsbooleanrequiredNo leave type is marked as a work accident and there were none: confirm it (else Bizisy can't count them).
establishmentsobject[]requiredPer 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_idstringrequired1–100 characters.
hours_workedinteger | nullrequiredFrom 0 to 999999999.
first_aid_workersinteger | nullrequiredFrom 0 to 999.
no_leaveobjectrequired2 fields
hintegerrequiredFrom 0 to 9999.
mintegerrequiredFrom 0 to 9999.
fatalobjectrequired2 fields
hintegerrequiredFrom 0 to 9999.
mintegerrequiredFrom 0 to 9999.
othersobjectrequired2 fields
hintegerrequiredFrom 0 to 9999.
mintegerrequiredFrom 0 to 9999.
providers_nonebooleanrequiredAnexo F: confirmed there were no service providers in the year.
providersintegerrequiredService providers listed for the year.
prefillobjectrequired6 fields
employees_31_decemberintegerrequiredemployees_averageintegerrequiredheadcount_31_octoberintegerrequiredWith 10 or more, Anexo 0 asks for section IX (accounts).
timeoffbooleanrequiredTime off is on: accidents are counted from it.
accident_typesintegerrequiredLeave types marked as work accidents (0: Bizisy can't count accidents).
establishmentsobject[]required8 fields
location_idstring | nullrequirednamestring | nullrequiredru_estabstring | nullrequiredemployeesintegerrequiredYearly average of employees.
contractorsintegerrequiredhours_estimateintegerrequiredEstimated hours worked (weekdays × weekly hours ÷ 5, less vacation, public holidays and work-accident days).
accidentsinteger | nullrequiredWork 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 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
}'const res = await fetch('https://api.bizisy.com/v1/country/relatorio_unico.annual.set', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"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
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/country/relatorio_unico.annual.set",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"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": None,
"health_head": None,
"employer": None,
"designated": None,
"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": None,
"no_leave": {
"h": 0,
"m": 1,
},
"fatal": {
"h": 0,
"m": 0,
},
"others": {
"h": 0,
"m": 0,
},
},
],
},
"providers_none": False,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
legal_entity_idstringrequired1–100 characters.
yearintegerrequiredFrom 2010 to 2100.
limitintegerFrom 1 to 500.
afterstring1–100 characters.
Returns
nonebooleanrequireditemsobject[]requiredA 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
idstringrequirednifstring | nullrequirednamestring | nullrequiredkind"1" | "2"requiredscheme"1" | "8"requirednissstring | nullrequiredactivity_type"1" | "2"requiredactivity_codestringrequiredengagementsobject[]required1–50 items.
4 fields
startstring | nullrequiredPattern
^\d{4}-\d{2}$.endstring | nullrequiredPattern
^\d{4}-\d{2}$.hoursinteger | nullrequiredA person: hours on the work.
From 1 to 9999.
workersinteger | nullrequiredA company: workers it placed.
From 1 to 99999.
source"app" | "csv"requiredupdated_atstringrequired
nextstring | nullrequiredThe after of the next page; null on the last.
totalintegerrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/country/relatorio_unico.providers.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"legal_entity_id": "le1",
"year": 2025,
"limit": 100,
"after": "pr1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/country/relatorio_unico.providers.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"legal_entity_id": "le1",
"year": 2025,
"limit": 100,
"after": "pr1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_saveon HR Assistant- Preview
?dry_run=trueruns 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_idstringrequired1–100 characters.
yearintegerrequiredFrom 2010 to 2100.
provider_idstring1–100 characters.
nifstringrequiredPattern
^\d{9}$.namestringrequired3–70 characters.
kind"1" | "2"requiredTable 54: 1 a person (singular), 2 a company (coletivo).
scheme"1" | "8"requiredTable 56: 1 Segurança Social, 8 another scheme.
nissstringrequiredNISS (11 digits with Segurança Social) or the other scheme's number.
1–20 characters.
activity_type"1" | "2"requiredTable 57: 1 CAE, 2 CIRS.
activity_codestringrequiredPattern
^\d{4,5}$.engagementsobject[]required1–50 items.
4 fields
startstring | nullrequiredPattern
^\d{4}-\d{2}$.endstring | nullrequiredPattern
^\d{4}-\d{2}$.hoursinteger | nullrequiredA person: hours on the work.
From 1 to 9999.
workersinteger | nullrequiredA company: workers it placed.
From 1 to 99999.
Returns
11 fields
idstringrequirednifstring | nullrequirednamestring | nullrequiredkind"1" | "2"requiredscheme"1" | "8"requirednissstring | nullrequiredactivity_type"1" | "2"requiredactivity_codestringrequiredengagementsobject[]required1–50 items.
4 fields
startstring | nullrequiredPattern
^\d{4}-\d{2}$.endstring | nullrequiredPattern
^\d{4}-\d{2}$.hoursinteger | nullrequiredA person: hours on the work.
From 1 to 9999.
workersinteger | nullrequiredA company: workers it placed.
From 1 to 99999.
source"app" | "csv"requiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
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
}
]
}'const res = await fetch('https://api.bizisy.com/v1/country/relatorio_unico.providers.save', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"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
}
]
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/country/relatorio_unico.providers.save",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"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": None,
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_removeon HR Assistant- Preview
?dry_run=trueruns 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_idstringrequired1–100 characters.
yearintegerrequiredFrom 2010 to 2100.
provider_idsstring[]1–100 characters. 1–200 items.
alltrue
Returns
removedintegerrequiredmorebooleanrequiredall: providers are left; call it again.
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
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"]}'const res = await fetch('https://api.bizisy.com/v1/country/relatorio_unico.providers.remove', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"legal_entity_id": "le1",
"year": 2025,
"provider_ids": [
"pr1"
]
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/country/relatorio_unico.providers.remove",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"legal_entity_id": "le1",
"year": 2025,
"provider_ids": [
"pr1",
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_importon HR Assistant- Preview
?dry_run=trueruns 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_idstringrequired1–100 characters.
yearintegerrequiredFrom 2010 to 2100.
rowsobject[]required1–1000 items.
11 fields
nifstringrequiredUp to 40 characters.
namestringrequiredUp to 200 characters.
typestringrequiredUp to 40 characters.
schemestringUp to 40 characters.
nissstringrequiredUp to 40 characters.
activity_typestringUp to 20 characters.
activity_codestringrequiredUp to 20 characters.
startstringUp to 20 characters.
endstringUp to 20 characters.
hoursstringUp to 20 characters.
workersstringUp to 20 characters.
Returns
createdintegerrequiredupdatedintegerrequiredleftintegerrequiredNew or changed providers not saved by this call: send the same rows again.
rowsobject[]required4 fields
rowintegerrequired1 = the first data row.
okbooleanrequiredcodestring | nullrequiredproblemstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
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"
}
]
}'const res = await fetch('https://api.bizisy.com/v1/country/relatorio_unico.providers.import', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"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"
}
]
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/country/relatorio_unico.providers.import",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"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",
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
yearintegerDefault: this year.
From 2020 to 2100.
legal_entity_idstring1–100 characters.
Returns
as_ofstringrequiredyearintegerrequiredentitiesobject[]required8 fields
legal_entityobjectrequired3 fields
idstringrequirednamestringrequiredcountrystringrequired
yearintegerrequiredbystringrequiredMade and posted by this day.
untilstringrequiredKept posted until this day.
lawstringrequiredsource_urlstringrequiredtimeoffbooleanrequiredFalse: time off is not on, so the map has no bookings.
locationsobject[]required9 fields
location_idstring | nullrequirednamestringrequiredThe workplace; empty for people without a location.
rowsobject[]requiredThe live map: each person with their approved vacation periods (start, end, working days).
4 fields
person_idstring | nullrequirednamestringrequiredperiodsobject[]required3 fields
startstringrequiredendstringrequireddaysnumberrequired
daysnumberrequired
peopleintegerrequiredpendingintegerrequiredVacation bookings not approved yet (not on the map).
state"not_due" | "due" | "overdue" | "posted" | "changed" | "closed"requirednot_due (more than a month before the deadline), due, overdue, posted, changed (bookings changed since the last posted version), closed (after the posting period).
changedbooleanrequiredpostedobject | nullrequired2 fields
versionintegerrequiredposted_onstringrequired
versionsobject[]required3 fields
versionintegerrequiredposted_onstringrequiredcreated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
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"}'const res = await fetch('https://api.bizisy.com/v1/country/vacation_map.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"year": 2026,
"legal_entity_id": "le1"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/country/vacation_map.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"year": 2026,
"legal_entity_id": "le1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_versionon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
legal_entity_idstringrequired1–100 characters.
location_idstring | nullrequiredThe workplace (location id), or null for people without a location.
1–100 characters.
yearintegerrequiredFrom 2020 to 2100.
versionintegerrequiredFrom 1 to 50.
Returns
versionintegerrequiredposted_onstringrequiredrowsobject[]required4 fields
person_idstring | nullrequirednamestringrequiredperiodsobject[]required3 fields
startstringrequiredendstringrequireddaysnumberrequired
daysnumberrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
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}'const res = await fetch('https://api.bizisy.com/v1/country/vacation_map.version', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"legal_entity_id": "le1",
"location_id": "l1",
"year": 2026,
"version": 1
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/country/vacation_map.version",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"legal_entity_id": "le1",
"location_id": "l1",
"year": 2026,
"version": 1,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_poston HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
legal_entity_idstringrequired1–100 characters.
location_idstring | nullrequiredThe workplace (location id), or null for people without a location.
1–100 characters.
yearintegerrequiredFrom 2020 to 2100.
posted_onstringPattern
^\d{4}-\d{2}-\d{2}$.
Returns
versionintegerrequiredposted_onstringrequiredpeopleintegerrequired
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
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"
}'const res = await fetch('https://api.bizisy.com/v1/country/vacation_map.post', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"legal_entity_id": "le1",
"location_id": null,
"year": 2026,
"posted_on": "2026-03-30"
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/country/vacation_map.post",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"legal_entity_id": "le1",
"location_id": None,
"year": 2026,
"posted_on": "2026-03-30",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
mode"law" | "on" | "off"requirednotestring | nullrequiredupdated_atstring | nullrequiredcountriesobject[]requiredEach country the company employs people in (or has a location in): its law and whether quiet hours apply.
8 fields
countrystringrequiredlawstringrequiredsource_urlstringrequiredmin_peopleinteger | nullrequirednotestringrequiredpeopleintegerrequiredActive people employed by legal entities in this country.
requiredbooleanrequiredThe 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 https://api.bizisy.com/v1/country/disconnect.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/country/disconnect.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/country/disconnect.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_updateon HR Assistant- Preview
?dry_run=trueruns 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 | nullUp to 4000 characters.
Returns
mode"law" | "on" | "off"requirednotestring | nullrequiredupdated_atstring | nullrequiredcountriesobject[]requiredEach country the company employs people in (or has a location in): its law and whether quiet hours apply.
8 fields
countrystringrequiredlawstringrequiredsource_urlstringrequiredmin_peopleinteger | nullrequirednotestringrequiredpeopleintegerrequiredActive people employed by legal entities in this country.
requiredbooleanrequiredThe 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 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."}'const res = await fetch('https://api.bizisy.com/v1/country/disconnect.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"note": "We do not expect answers outside working hours."
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/country/disconnect.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"note": "We do not expect answers outside working hours.",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_mineon My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
8 fields
appliesbooleanrequiredquiet_nowbooleanrequirednext_deliverystring | nullrequiredWhen held notices go out (null: not in quiet hours).
time_zonestring | nullrequiredperiodsobject[]requiredYour working periods in the next 7 days.
2 fields
startstringrequiredendstringrequired
notestring | nullrequiredlawstring | nullrequiredsource_urlstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/country/disconnect.mine \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/country/disconnect.mine', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/country/disconnect.mine",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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_whenon My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
person_idsstring[]required1–64 characters. 1–50 items.
Returns
peopleobject[]required4 fields
person_idstringrequiredquietbooleanrequireddeliver_atstring | nullrequiredtime_zonestringrequired
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
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"]}'const res = await fetch('https://api.bizisy.com/v1/country/disconnect.when', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"person_ids": [
"p1",
"p2"
]
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/country/disconnect.when",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"person_ids": [
"p1",
"p2",
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"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.