API reference
Employee relations
Disciplinary cases with the deadlines from the law (Portugal, Spain; the company's own periods elsewhere), the case file, case teams, evidence requests, the case assistant (AI reading of case documents) and settings. Every action works only in the Bizisy app: API keys and connected AI apps are refused, reads included, because a case is confidential to its team.
36 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.
My access to Employee relations#
POST/v1/relations/access.meRead
Whether the caller may open new cases (ER staff), sees the register (owners and admins) and how many open cases they are on. In the app only: machines are refused.
- Web app only
- Refused for API keys and connected apps. Employee relations works only in the Bizisy app: a case is confidential to its team.
- MCP tool
relations_access_meon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
onbooleanrequiredEmployee relations shows for this login: ER staff, the register, or on a case.
staffbooleanrequiredregisterbooleanrequiredcasesintegerrequiredsettingsbooleanrequiredmineobject[]requiredYour open cases, most urgent first (at most 20): ⌘K opens them by number.
2 fields
idstringrequirednumberstringrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/access.me \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/relations/access.me', {
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/relations/access.me",
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": {
"on": true,
"staff": true,
"register": false,
"cases": 1,
"settings": false,
"mine": [
{
"id": "c1",
"number": "ER-2026-0001"
}
]
}
}List employee relations cases#
POST/v1/relations/cases.listRead
Cases the caller is on (view mine), or for owners and admins the register (view register): number, person, kind, step, next deadline, team, legal hold. The register carries no facts, evidence or letters. Anyone else sees no case at all; the person a case is about never sees theirs here. Filter by status (open, closed, all), kind and a case number. In the app only: API keys and AI apps are refused.
- Web app only
- Refused for API keys and connected apps. Employee relations works only in the Bizisy app: a case is confidential to its team.
- MCP tool
relations_cases_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
view"mine" | "register"Default
"mine".status"open" | "closed" | "all"Default
"open".kind"dismissal" | "sanction" | "abandonment" | "inquiry"qstringA case number, or part of one.
Up to 40 characters.
Returns
itemsobject[]required14 fields
idstringrequirednumberstringrequiredkind"dismissal" | "sanction" | "abandonment" | "inquiry"requiredstatus"open" | "closed"requiredphasestring (enum)requiredOne of:
facts,inquiry,defence,evidence,opinion,decision,decided,applied,absence,letter_sent,closed.personobject | nullrequired2 fields
idstringrequirednamestringrequired
nextobject | nullrequired6 fields
labelstringrequiredbasisstringrequiredduestringrequireddays_leftintegerrequiredstate"waiting" | "running" | "ended" | "met" | "missed" | "info"requiredlapsebooleanrequired
lapsedbooleanrequiredholdbooleanrequiredteamobject[]required4 fields
user_idstringrequirednamestringrequiredrole"lead" | "member" | "decider" | "reviewer"requiredvia_break_glassbooleanrequired
my_role"lead" | "member" | "decider" | "reviewer"requirednull: a register row (owners and admins, not on the team).
opened_onstringrequiredclosed_atstring | nullrequiredoutcome"no_sanction" | "sanction" | "dismissal" | "dropped" | "resigned" | "abandonment"required
totalintegerrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/cases.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"view":"register","status":"all"}'const res = await fetch('https://api.bizisy.com/v1/relations/cases.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"view": "register",
"status": "all"
}),
});
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/relations/cases.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"view": "register",
"status": "all",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"items": [
{
"id": "c1",
"number": "ER-2026-0001",
"kind": "dismissal",
"status": "open",
"phase": "defence",
"person": {
"id": "p2",
"name": "Bea Silva"
},
"next": {
"label": "Defence period",
"basis": "CT 355(1)",
"due": "2026-12-07",
"days_left": 14,
"state": "running",
"lapse": false
},
"lapsed": false,
"hold": false,
"team": [
{
"user_id": "u1",
"name": "Rui Lopes",
"role": "lead",
"via_break_glass": false
}
],
"my_role": "lead",
"opened_on": "2026-11-05",
"closed_at": null,
"outcome": null
}
],
"total": 1
}
}Open an employee relations case#
POST/v1/relations/cases.getRead
The whole case for someone on its team: facts, flags, every clock with its article and what stops it, the next three deadlines, the procedure check before the written charges and before the decision, protected-situation warnings, the timeline, the case file (evidence with provenance, uploads, statements), evidence requests and, in Portugal, the count of confirmed unjustified absences. Anyone not on the team (owners, admins and HR included) gets not_found. In the app only.
- Web app only
- Refused for API keys and connected apps. Employee relations works only in the Bizisy app: a case is confidential to its team.
- MCP tool
relations_cases_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
case_idstringrequired1–64 characters.
Returns
36 fields
idstringrequirednumberstringrequiredkind"dismissal" | "sanction" | "abandonment" | "inquiry"requiredstatus"open" | "closed"requiredphasestring (enum)requiredOne of:
facts,inquiry,defence,evidence,opinion,decision,decided,applied,absence,letter_sent,closed.personobject | nullrequired2 fields
idstringrequirednamestringrequired
nextobject | nullrequired6 fields
labelstringrequiredbasisstringrequiredduestringrequireddays_leftintegerrequiredstate"waiting" | "running" | "ended" | "met" | "missed" | "info"requiredlapsebooleanrequired
lapsedbooleanrequiredholdbooleanrequiredteamobject[]required4 fields
user_idstringrequirednamestringrequiredrole"lead" | "member" | "decider" | "reviewer"requiredvia_break_glassbooleanrequired
my_role"lead" | "member" | "decider" | "reviewer"requirednull: a register row (owners and admins, not on the team).
opened_onstringrequiredclosed_atstring | nullrequiredoutcome"no_sanction" | "sanction" | "dismissal" | "dropped" | "resigned" | "abandonment"requiredpackobjectrequired7 fields
id"pt" | "es" | "eu"requiredversionstringrequirednamestringrequiredlegalbooleanrequirednotestringrequiredcurrent_versionstringrequirednewerbooleanrequired
countrystring | nullrequiredfactsobject[]required7 fields
idstringrequiredtitlestringrequireddatesstring[]requiredlearned_onstring | nullrequiredcrimebooleanrequiredcrime_untilstring | nullrequiredseverity"leve" | "grave" | "muy_grave"required
flagsobjectrequired9 fields
repbooleanrequiredunionbooleanrequiredcandidatebooleanrequiredmicrobooleanrequiredcouncilbooleanrequiredparentalbooleanrequiredcomplaint_onstring | nullrequiredequality_complaintbooleanrequiredwhistleblowerbooleanrequired
parental_from_timeoffbooleanrequiredabsent_sincestring | nullrequiredclocksobject[]required16 fields
keystringrequiredclockstringrequiredtype"deadline" | "wait" | "info"requiredfact_idstring | nullrequiredlabelstringrequiredEnglish; the app translates it.
basisstringrequiredThe article, untranslated: "CT 329(2)".
urlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredstopsstringrequiredif_missedstringrequiredlapsebooleanrequiredstarted_onstring | nullrequiredduestring | nullrequiredstate"waiting" | "running" | "ended" | "met" | "missed" | "info"requireddays_leftinteger | nullrequirednotestring | nullrequired
next3object[]required16 fields
keystringrequiredclockstringrequiredtype"deadline" | "wait" | "info"requiredfact_idstring | nullrequiredlabelstringrequiredEnglish; the app translates it.
basisstringrequiredThe article, untranslated: "CT 329(2)".
urlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredstopsstringrequiredif_missedstringrequiredlapsebooleanrequiredstarted_onstring | nullrequiredduestring | nullrequiredstate"waiting" | "running" | "ended" | "met" | "missed" | "info"requireddays_leftinteger | nullrequirednotestring | nullrequired
checksobjectrequired2 fields
chargesobject[]required7 fields
idstringrequiredmessagestringrequiredEnglish with {n}, {date}, {clock} filled from values.
basisstringrequiredurlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredlevel"red" | "warning" | "info"requiredvaluesobjectrequired
decisionobject[]required7 fields
idstringrequiredmessagestringrequiredEnglish with {n}, {date}, {clock} filled from values.
basisstringrequiredurlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredlevel"red" | "warning" | "info"requiredvaluesobjectrequired
protectedobject[]required7 fields
idstringrequiredmessagestringrequiredEnglish with {n}, {date}, {clock} filled from values.
basisstringrequiredurlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredlevel"red" | "warning" | "info"requiredvaluesobjectrequired
person_factsobject | nullrequired10 fields
idstringrequirednamestringrequiredstatusstringrequiredtitlestring | nullrequiredteamstring | nullrequiredlocationstring | nullrequiredcountrystring | nullrequiredcontract_typestring | nullrequiredstartstring | nullrequiredlast_daystring | nullrequired
eventsobject[]required11 fields
idstringrequiredkindstring (enum)requiredOne of:
inquiry_started,inquiry_ended,suspension_started,suspension_ended,charges_delivered,defence_extended,defence_received,union_named,evidence_requested,evidence_done,evidence_refused,hearing_offered,hearing_held,expediente_opened,file_to_council,opinion_received,cite_sent,cite_opinion,decision_delivered,sanction_applied,contact_recorded,registered_letter_sent,claim_filed,claim_ended,note,item_removed,converted,closed,reopened.labelstringrequireddatestringrequiredreceived_onstring | nullrequireddue_onstring | nullrequiredrefstring | nullrequirednotestring | nullrequireditem_idsstring[]requiredbyobjectrequired2 fields
user_idstringrequirednamestringrequired
atstringrequired
itemsobject[]required16 fields
idstringrequireddoc_nostringrequiredkind"record" | "file" | "statement"requiredrole"evidence" | "defence" | "statement" | "proof" | "opinion" | "other"requiredlabelstringrequiredonstring | nullrequiredsourceobject | nullrequired4 fields
modulestringrequiredtypestring (enum)requiredOne of:
timeclock_no_record,timeclock_late,timeoff,shifts,training_assigned,training_failed,documents,org_facts,earlier_case.refstringrequiredhashstringrequired
snapshotobject | nullrequiredfileobject | nullrequired6 fields
namestringrequiredcontent_typestringrequiredsizeintegerrequiredsha256string | nullrequiredpagesinteger | nullrequiredstatus"pending" | "ready"required
emailobject | nullrequired8 fields
fromstring | nullrequiredtostring | nullrequiredccstring | nullrequireddatestring | nullrequiredsubjectstring | nullrequiredtextstringrequiredtruncatedbooleanrequiredattachmentsobject[]required5 fields
indexintegerrequirednamestringrequiredcontent_typestringrequiredsizeintegerrequiredextracted_item_idstring | nullrequired
statementstring | nullrequiredconfirmed"unjustified" | "justified"requiredfrom_requestobject | nullrequired2 fields
request_idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
linked_byobjectrequired2 fields
user_idstringrequirednamestringrequired
linked_atstringrequiredremovedobject | nullrequired3 fields
atstringrequiredbystringrequiredreasonstring | nullrequired
requestsobject[]required8 fields
idstringrequiredtoobjectrequired2 fields
idstringrequirednamestringrequired
askstringrequiredduestring | nullrequiredstatus"open" | "answered" | "cancelled" | "expired"requiredanswered_atstring | nullrequireditem_idsstring[]requiredatstringrequired
counterobject | nullrequired5 fields
yearintegerrequiredtotalintegerrequiredlongest_runintegerrequiredreachesbooleanrequiredunconfirmedintegerrequired
allowed_eventsstring (enum)[]requiredOne of:
inquiry_started,inquiry_ended,suspension_started,suspension_ended,charges_delivered,defence_extended,defence_received,union_named,evidence_requested,evidence_done,evidence_refused,hearing_offered,hearing_held,expediente_opened,file_to_council,opinion_received,cite_sent,cite_opinion,decision_delivered,sanction_applied,contact_recorded,registered_letter_sent,claim_filed,claim_ended,note,item_removed,converted,closed,reopened.retention_untilstring | nullrequiredmeobjectrequired3 fields
lettersbooleanrequiredanswerbooleanrequiredconsultbooleanrequired
canobjectrequired2 fields
editbooleanrequiredleadbooleanrequired
filesobjectrequired4 fields
countintegerrequiredbytesintegerrequiredmax_filesintegerrequiredmax_bytesintegerrequired
bundleobjectrequired2 fields
lastobject | nullrequired2 fields
atstringrequiredpagesintegerrequired
left_todayintegerrequired
todaystringrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/cases.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"case_id":"c1"}'const res = await fetch('https://api.bizisy.com/v1/relations/cases.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"case_id": "c1"
}),
});
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/relations/cases.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"case_id": "c1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "c1",
"number": "ER-2026-0001",
"kind": "dismissal",
"status": "open",
"phase": "defence",
"person": {
"id": "p2",
"name": "Bea Silva"
},
"next": {
"label": "Defence period",
"basis": "CT 355(1)",
"due": "2026-12-07",
"days_left": 14,
"state": "running",
"lapse": false
},
"lapsed": false,
"hold": false,
"team": [
{
"user_id": "u1",
"name": "Rui Lopes",
"role": "lead",
"via_break_glass": false
}
],
"my_role": "lead",
"opened_on": "2026-11-05",
"closed_at": null,
"outcome": null,
"pack": {
"id": "pt",
"version": "2026-11-22",
"name": "Portugal: Código do Trabalho",
"legal": true,
"note": "Deadlines from the Código do Trabalho.",
"current_version": "2026-11-22",
"newer": false
},
"country": "PT",
"facts": [
{
"id": "f1",
"title": "Absent without notice",
"dates": [
"2026-11-03"
],
"learned_on": "2026-11-05",
"crime": false,
"crime_until": null,
"severity": null
}
],
"flags": {
"rep": false,
"union": false,
"candidate": false,
"micro": false,
"council": false,
"parental": false,
"complaint_on": null,
"equality_complaint": false,
"whistleblower": false
},
"parental_from_timeoff": false,
"absent_since": null,
"clocks": [
{
"key": "C6",
"clock": "C6",
"type": "wait",
"fact_id": null,
"label": "Defence period",
"basis": "CT 355(1)",
"url": "https://www.pgdlisboa.pt/leis/lei_mostra_articulado.php?artigo_id=1047A0355&nid=1047&tabela=leis",
"confidence": "verified",
"stops": "The answer received early, or an extension the team grants (recorded)",
"if_missed": "The team may go on with the procedure.",
"lapse": false,
"started_on": "2026-11-20",
"due": "2026-12-07",
"state": "running",
"days_left": 14,
"note": null
}
],
"next3": [
{
"key": "C6",
"clock": "C6",
"type": "wait",
"fact_id": null,
"label": "Defence period",
"basis": "CT 355(1)",
"url": "https://www.pgdlisboa.pt/leis/lei_mostra_articulado.php?artigo_id=1047A0355&nid=1047&tabela=leis",
"confidence": "verified",
"stops": "The answer received early, or an extension the team grants (recorded)",
"if_missed": "The team may go on with the procedure.",
"lapse": false,
"started_on": "2026-11-20",
"due": "2026-12-07",
"state": "running",
"days_left": 14,
"note": null
}
],
"checks": {
"charges": [],
"decision": [
{
"id": "defence_open",
"message": "The defence period isn't over.",
"basis": "CT 355",
"url": "https://www.pgdlisboa.pt/leis/lei_mostra_articulado.php?artigo_id=1047A0355&nid=1047&tabela=leis",
"confidence": "verified",
"level": "red",
"values": {}
}
]
},
"protected": [],
"person_facts": {
"id": "p2",
"name": "Bea Silva",
"status": "active",
"title": "Agent",
"team": "Support",
"location": "Lisboa",
"country": "PT",
"contract_type": "open_ended",
"start": "2024-01-08",
"last_day": null
},
"events": [
{
"id": "e1",
"kind": "charges_delivered",
"label": "Nota de culpa delivered",
"date": "2026-11-18",
"received_on": "2026-11-20",
"due_on": null,
"ref": null,
"note": null,
"item_ids": [],
"by": {
"user_id": "u1",
"name": "Rui Lopes"
},
"at": "2026-11-21T10:00:00.000Z"
}
],
"items": [
{
"id": "i1",
"doc_no": "D-1",
"kind": "record",
"role": "evidence",
"label": "No record, 2026-11-03, scheduled 09:00–18:00",
"on": "2026-11-03",
"source": {
"module": "timeclock",
"type": "timeclock_no_record",
"ref": "no_record:2026-11-03",
"hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
},
"snapshot": {
"date": "2026-11-03",
"start": "09:00",
"end": "18:00"
},
"file": null,
"email": null,
"statement": null,
"confirmed": null,
"from_request": null,
"linked_by": {
"user_id": "u1",
"name": "Rui Lopes"
},
"linked_at": "2026-11-21T10:00:00.000Z",
"removed": null
}
],
"requests": [],
"counter": {
"year": 2026,
"total": 0,
"longest_run": 0,
"reaches": false,
"unconfirmed": 1
},
"allowed_events": [
"charges_delivered",
"defence_received",
"note"
],
"retention_until": null,
"me": {
"letters": true,
"answer": true,
"consult": true
},
"can": {
"edit": true,
"lead": true
},
"files": {
"count": 0,
"bytes": 0,
"max_files": 500,
"max_bytes": 2000000000
},
"bundle": {
"last": null,
"left_today": 10
},
"today": "2026-11-23"
}
}Open an employee relations case#
POST/v1/relations/cases.openWrite
Opens a case about an active person (ER staff only): the kind (dismissal, sanction, abandonment, inquiry), the facts as short titles with their dates and the day the employer learned of each, ticks (representative, union member, micro-enterprise, works council, parental, a recent complaint, whistleblowing) and the team (you are the lead; add a decider and others). A dry run returns the dates the rule pack computes ("Start the procedure by …", CT 329(2)), the protected-situation warnings and who on the team manages the person (they need confirm_chain). The case number ER-<year>-<seq> is the only identifier in emails and Activity. Up to 20 facts and 20 team members; 5000 open cases a company. Nobody is notified, and the person learns nothing. In the app only.
- Web app only
- Refused for API keys and connected apps. Employee relations works only in the Bizisy app: a case is confidential to its team.
- MCP tool
relations_cases_openon 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
person_idstringrequired1–64 characters.
kind"dismissal" | "sanction" | "abandonment" | "inquiry"requiredfactsobject[]Up to 20 items.
7 fields
idstringUp to 20 characters.
titlestringrequiredA one-line title in your words, e.g. "Absent without notice on 3, 4 and 5 November".
1–160 characters.
datesstring[]The infraction dates (continued conduct: its last date).
Up to 50 items. Pattern
^\d{4}-\d{2}-\d{2}$.learned_onstring | nullThe day the employer or the superior with disciplinary power learned of it.
Pattern
^\d{4}-\d{2}-\d{2}$. Defaultnull.crimebooleanMay also be a crime (the criminal-law period applies; never upload criminal records).
Default
false.crime_untilstring | nullPattern
^\d{4}-\d{2}-\d{2}$. Defaultnull.severity"leve" | "grave" | "muy_grave"Spain: the convenio severity.
Default
null.
flagsobjectDefault
{}.9 fields
repbooleanunionbooleancandidatebooleanmicrobooleancouncilbooleanparentalbooleancomplaint_onstring | nullPattern
^\d{4}-\d{2}-\d{2}$.equality_complaintbooleanwhistleblowerboolean
absent_sincestring | nullAbandonment: the first day absent with no word.
Pattern
^\d{4}-\d{2}-\d{2}$. Defaultnull.teamobject[]Others on the team; you are the lead.
Up to 20 items.
2 fields
user_idstringrequired1–64 characters.
role"lead" | "member" | "decider" | "reviewer"required
confirm_chainbooleantrue: you saw that someone on the team manages the person.
Default
false.
Returns
7 fields
idstring | nullrequirednumberstringrequiredpackobjectrequired7 fields
id"pt" | "es" | "eu"requiredversionstringrequirednamestringrequiredlegalbooleanrequirednotestringrequiredcurrent_versionstringrequirednewerbooleanrequired
clocksobject[]required16 fields
keystringrequiredclockstringrequiredtype"deadline" | "wait" | "info"requiredfact_idstring | nullrequiredlabelstringrequiredEnglish; the app translates it.
basisstringrequiredThe article, untranslated: "CT 329(2)".
urlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredstopsstringrequiredif_missedstringrequiredlapsebooleanrequiredstarted_onstring | nullrequiredduestring | nullrequiredstate"waiting" | "running" | "ended" | "met" | "missed" | "info"requireddays_leftinteger | nullrequirednotestring | nullrequired
start_byobject | nullrequired16 fields
keystringrequiredclockstringrequiredtype"deadline" | "wait" | "info"requiredfact_idstring | nullrequiredlabelstringrequiredEnglish; the app translates it.
basisstringrequiredThe article, untranslated: "CT 329(2)".
urlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredstopsstringrequiredif_missedstringrequiredlapsebooleanrequiredstarted_onstring | nullrequiredduestring | nullrequiredstate"waiting" | "running" | "ended" | "met" | "missed" | "info"requireddays_leftinteger | nullrequirednotestring | nullrequired
protectedobject[]required7 fields
idstringrequiredmessagestringrequiredEnglish with {n}, {date}, {clock} filled from values.
basisstringrequiredurlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredlevel"red" | "warning" | "info"requiredvaluesobjectrequired
chainobject[]requiredTeam members who manage the person: they will see the whole case.
2 fields
user_idstringrequirednamestringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/cases.open \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"person_id": "p2",
"kind": "dismissal",
"facts": [
{
"title": "Absent without notice",
"dates": [
"2026-11-03"
],
"learned_on": "2026-11-05"
}
],
"team": [
{
"user_id": "u2",
"role": "decider"
}
]
}'const res = await fetch('https://api.bizisy.com/v1/relations/cases.open', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_id": "p2",
"kind": "dismissal",
"facts": [
{
"title": "Absent without notice",
"dates": [
"2026-11-03"
],
"learned_on": "2026-11-05"
}
],
"team": [
{
"user_id": "u2",
"role": "decider"
}
]
}),
});
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/relations/cases.open",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p2",
"kind": "dismissal",
"facts": [
{
"title": "Absent without notice",
"dates": [
"2026-11-03",
],
"learned_on": "2026-11-05",
},
],
"team": [
{
"user_id": "u2",
"role": "decider",
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "c1",
"number": "ER-2026-0001",
"pack": {
"id": "pt",
"version": "2026-11-22",
"name": "Portugal: Código do Trabalho",
"legal": true,
"note": "Deadlines from the Código do Trabalho.",
"current_version": "2026-11-22",
"newer": false
},
"clocks": [
{
"key": "C6",
"clock": "C6",
"type": "wait",
"fact_id": null,
"label": "Defence period",
"basis": "CT 355(1)",
"url": "https://www.pgdlisboa.pt/leis/lei_mostra_articulado.php?artigo_id=1047A0355&nid=1047&tabela=leis",
"confidence": "verified",
"stops": "The answer received early, or an extension the team grants (recorded)",
"if_missed": "The team may go on with the procedure.",
"lapse": false,
"started_on": "2026-11-20",
"due": "2026-12-07",
"state": "running",
"days_left": 14,
"note": null
}
],
"start_by": {
"key": "C6",
"clock": "C6",
"type": "wait",
"fact_id": null,
"label": "Defence period",
"basis": "CT 355(1)",
"url": "https://www.pgdlisboa.pt/leis/lei_mostra_articulado.php?artigo_id=1047A0355&nid=1047&tabela=leis",
"confidence": "verified",
"stops": "The answer received early, or an extension the team grants (recorded)",
"if_missed": "The team may go on with the procedure.",
"lapse": false,
"started_on": "2026-11-20",
"due": "2026-12-07",
"state": "running",
"days_left": 14,
"note": null
},
"protected": [],
"chain": []
}
}Change a case's facts or ticks#
POST/v1/relations/cases.updateWrite
Changes an open case's facts (titles, dates, when the employer learned, crime, severity), ticks, the first day of an abandonment absence, the My workspace options (lead only), or moves it to the newest rule set (pack_version: "current", lead only; a newer set never moves dates silently). The lead and members; the decider and reviewer only read. Recomputes every clock. In the app only.
- Web app only
- Refused for API keys and connected apps. Employee relations works only in the Bizisy app: a case is confidential to its team.
- MCP tool
relations_cases_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
case_idstringrequired1–64 characters.
factsobject[]Up to 20 items.
7 fields
idstringUp to 20 characters.
titlestringrequiredA one-line title in your words, e.g. "Absent without notice on 3, 4 and 5 November".
1–160 characters.
datesstring[]The infraction dates (continued conduct: its last date).
Up to 50 items. Pattern
^\d{4}-\d{2}-\d{2}$.learned_onstring | nullThe day the employer or the superior with disciplinary power learned of it.
Pattern
^\d{4}-\d{2}-\d{2}$. Defaultnull.crimebooleanMay also be a crime (the criminal-law period applies; never upload criminal records).
Default
false.crime_untilstring | nullPattern
^\d{4}-\d{2}-\d{2}$. Defaultnull.severity"leve" | "grave" | "muy_grave"Spain: the convenio severity.
Default
null.
flagsobject9 fields
repbooleanunionbooleancandidatebooleanmicrobooleancouncilbooleanparentalbooleancomplaint_onstring | nullPattern
^\d{4}-\d{2}-\d{2}$.equality_complaintbooleanwhistleblowerboolean
absent_sincestring | nullPattern
^\d{4}-\d{2}-\d{2}$.meobject3 fields
lettersbooleananswerbooleanconsultboolean
pack_version"current"
Returns
36 fields
idstringrequirednumberstringrequiredkind"dismissal" | "sanction" | "abandonment" | "inquiry"requiredstatus"open" | "closed"requiredphasestring (enum)requiredOne of:
facts,inquiry,defence,evidence,opinion,decision,decided,applied,absence,letter_sent,closed.personobject | nullrequired2 fields
idstringrequirednamestringrequired
nextobject | nullrequired6 fields
labelstringrequiredbasisstringrequiredduestringrequireddays_leftintegerrequiredstate"waiting" | "running" | "ended" | "met" | "missed" | "info"requiredlapsebooleanrequired
lapsedbooleanrequiredholdbooleanrequiredteamobject[]required4 fields
user_idstringrequirednamestringrequiredrole"lead" | "member" | "decider" | "reviewer"requiredvia_break_glassbooleanrequired
my_role"lead" | "member" | "decider" | "reviewer"requirednull: a register row (owners and admins, not on the team).
opened_onstringrequiredclosed_atstring | nullrequiredoutcome"no_sanction" | "sanction" | "dismissal" | "dropped" | "resigned" | "abandonment"requiredpackobjectrequired7 fields
id"pt" | "es" | "eu"requiredversionstringrequirednamestringrequiredlegalbooleanrequirednotestringrequiredcurrent_versionstringrequirednewerbooleanrequired
countrystring | nullrequiredfactsobject[]required7 fields
idstringrequiredtitlestringrequireddatesstring[]requiredlearned_onstring | nullrequiredcrimebooleanrequiredcrime_untilstring | nullrequiredseverity"leve" | "grave" | "muy_grave"required
flagsobjectrequired9 fields
repbooleanrequiredunionbooleanrequiredcandidatebooleanrequiredmicrobooleanrequiredcouncilbooleanrequiredparentalbooleanrequiredcomplaint_onstring | nullrequiredequality_complaintbooleanrequiredwhistleblowerbooleanrequired
parental_from_timeoffbooleanrequiredabsent_sincestring | nullrequiredclocksobject[]required16 fields
keystringrequiredclockstringrequiredtype"deadline" | "wait" | "info"requiredfact_idstring | nullrequiredlabelstringrequiredEnglish; the app translates it.
basisstringrequiredThe article, untranslated: "CT 329(2)".
urlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredstopsstringrequiredif_missedstringrequiredlapsebooleanrequiredstarted_onstring | nullrequiredduestring | nullrequiredstate"waiting" | "running" | "ended" | "met" | "missed" | "info"requireddays_leftinteger | nullrequirednotestring | nullrequired
next3object[]required16 fields
keystringrequiredclockstringrequiredtype"deadline" | "wait" | "info"requiredfact_idstring | nullrequiredlabelstringrequiredEnglish; the app translates it.
basisstringrequiredThe article, untranslated: "CT 329(2)".
urlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredstopsstringrequiredif_missedstringrequiredlapsebooleanrequiredstarted_onstring | nullrequiredduestring | nullrequiredstate"waiting" | "running" | "ended" | "met" | "missed" | "info"requireddays_leftinteger | nullrequirednotestring | nullrequired
checksobjectrequired2 fields
chargesobject[]required7 fields
idstringrequiredmessagestringrequiredEnglish with {n}, {date}, {clock} filled from values.
basisstringrequiredurlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredlevel"red" | "warning" | "info"requiredvaluesobjectrequired
decisionobject[]required7 fields
idstringrequiredmessagestringrequiredEnglish with {n}, {date}, {clock} filled from values.
basisstringrequiredurlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredlevel"red" | "warning" | "info"requiredvaluesobjectrequired
protectedobject[]required7 fields
idstringrequiredmessagestringrequiredEnglish with {n}, {date}, {clock} filled from values.
basisstringrequiredurlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredlevel"red" | "warning" | "info"requiredvaluesobjectrequired
person_factsobject | nullrequired10 fields
idstringrequirednamestringrequiredstatusstringrequiredtitlestring | nullrequiredteamstring | nullrequiredlocationstring | nullrequiredcountrystring | nullrequiredcontract_typestring | nullrequiredstartstring | nullrequiredlast_daystring | nullrequired
eventsobject[]required11 fields
idstringrequiredkindstring (enum)requiredOne of:
inquiry_started,inquiry_ended,suspension_started,suspension_ended,charges_delivered,defence_extended,defence_received,union_named,evidence_requested,evidence_done,evidence_refused,hearing_offered,hearing_held,expediente_opened,file_to_council,opinion_received,cite_sent,cite_opinion,decision_delivered,sanction_applied,contact_recorded,registered_letter_sent,claim_filed,claim_ended,note,item_removed,converted,closed,reopened.labelstringrequireddatestringrequiredreceived_onstring | nullrequireddue_onstring | nullrequiredrefstring | nullrequirednotestring | nullrequireditem_idsstring[]requiredbyobjectrequired2 fields
user_idstringrequirednamestringrequired
atstringrequired
itemsobject[]required16 fields
idstringrequireddoc_nostringrequiredkind"record" | "file" | "statement"requiredrole"evidence" | "defence" | "statement" | "proof" | "opinion" | "other"requiredlabelstringrequiredonstring | nullrequiredsourceobject | nullrequired4 fields
modulestringrequiredtypestring (enum)requiredOne of:
timeclock_no_record,timeclock_late,timeoff,shifts,training_assigned,training_failed,documents,org_facts,earlier_case.refstringrequiredhashstringrequired
snapshotobject | nullrequiredfileobject | nullrequired6 fields
namestringrequiredcontent_typestringrequiredsizeintegerrequiredsha256string | nullrequiredpagesinteger | nullrequiredstatus"pending" | "ready"required
emailobject | nullrequired8 fields
fromstring | nullrequiredtostring | nullrequiredccstring | nullrequireddatestring | nullrequiredsubjectstring | nullrequiredtextstringrequiredtruncatedbooleanrequiredattachmentsobject[]required5 fields
indexintegerrequirednamestringrequiredcontent_typestringrequiredsizeintegerrequiredextracted_item_idstring | nullrequired
statementstring | nullrequiredconfirmed"unjustified" | "justified"requiredfrom_requestobject | nullrequired2 fields
request_idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
linked_byobjectrequired2 fields
user_idstringrequirednamestringrequired
linked_atstringrequiredremovedobject | nullrequired3 fields
atstringrequiredbystringrequiredreasonstring | nullrequired
requestsobject[]required8 fields
idstringrequiredtoobjectrequired2 fields
idstringrequirednamestringrequired
askstringrequiredduestring | nullrequiredstatus"open" | "answered" | "cancelled" | "expired"requiredanswered_atstring | nullrequireditem_idsstring[]requiredatstringrequired
counterobject | nullrequired5 fields
yearintegerrequiredtotalintegerrequiredlongest_runintegerrequiredreachesbooleanrequiredunconfirmedintegerrequired
allowed_eventsstring (enum)[]requiredOne of:
inquiry_started,inquiry_ended,suspension_started,suspension_ended,charges_delivered,defence_extended,defence_received,union_named,evidence_requested,evidence_done,evidence_refused,hearing_offered,hearing_held,expediente_opened,file_to_council,opinion_received,cite_sent,cite_opinion,decision_delivered,sanction_applied,contact_recorded,registered_letter_sent,claim_filed,claim_ended,note,item_removed,converted,closed,reopened.retention_untilstring | nullrequiredmeobjectrequired3 fields
lettersbooleanrequiredanswerbooleanrequiredconsultbooleanrequired
canobjectrequired2 fields
editbooleanrequiredleadbooleanrequired
filesobjectrequired4 fields
countintegerrequiredbytesintegerrequiredmax_filesintegerrequiredmax_bytesintegerrequired
bundleobjectrequired2 fields
lastobject | nullrequired2 fields
atstringrequiredpagesintegerrequired
left_todayintegerrequired
todaystringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/cases.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"case_id":"c1","flags":{"council":true}}'const res = await fetch('https://api.bizisy.com/v1/relations/cases.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"case_id": "c1",
"flags": {
"council": 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/relations/cases.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"case_id": "c1",
"flags": {
"council": True,
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "c1",
"number": "ER-2026-0001",
"kind": "dismissal",
"status": "open",
"phase": "defence",
"person": {
"id": "p2",
"name": "Bea Silva"
},
"next": {
"label": "Defence period",
"basis": "CT 355(1)",
"due": "2026-12-07",
"days_left": 14,
"state": "running",
"lapse": false
},
"lapsed": false,
"hold": false,
"team": [
{
"user_id": "u1",
"name": "Rui Lopes",
"role": "lead",
"via_break_glass": false
}
],
"my_role": "lead",
"opened_on": "2026-11-05",
"closed_at": null,
"outcome": null,
"pack": {
"id": "pt",
"version": "2026-11-22",
"name": "Portugal: Código do Trabalho",
"legal": true,
"note": "Deadlines from the Código do Trabalho.",
"current_version": "2026-11-22",
"newer": false
},
"country": "PT",
"facts": [
{
"id": "f1",
"title": "Absent without notice",
"dates": [
"2026-11-03"
],
"learned_on": "2026-11-05",
"crime": false,
"crime_until": null,
"severity": null
}
],
"flags": {
"rep": false,
"union": false,
"candidate": false,
"micro": false,
"council": false,
"parental": false,
"complaint_on": null,
"equality_complaint": false,
"whistleblower": false
},
"parental_from_timeoff": false,
"absent_since": null,
"clocks": [
{
"key": "C6",
"clock": "C6",
"type": "wait",
"fact_id": null,
"label": "Defence period",
"basis": "CT 355(1)",
"url": "https://www.pgdlisboa.pt/leis/lei_mostra_articulado.php?artigo_id=1047A0355&nid=1047&tabela=leis",
"confidence": "verified",
"stops": "The answer received early, or an extension the team grants (recorded)",
"if_missed": "The team may go on with the procedure.",
"lapse": false,
"started_on": "2026-11-20",
"due": "2026-12-07",
"state": "running",
"days_left": 14,
"note": null
}
],
"next3": [
{
"key": "C6",
"clock": "C6",
"type": "wait",
"fact_id": null,
"label": "Defence period",
"basis": "CT 355(1)",
"url": "https://www.pgdlisboa.pt/leis/lei_mostra_articulado.php?artigo_id=1047A0355&nid=1047&tabela=leis",
"confidence": "verified",
"stops": "The answer received early, or an extension the team grants (recorded)",
"if_missed": "The team may go on with the procedure.",
"lapse": false,
"started_on": "2026-11-20",
"due": "2026-12-07",
"state": "running",
"days_left": 14,
"note": null
}
],
"checks": {
"charges": [],
"decision": [
{
"id": "defence_open",
"message": "The defence period isn't over.",
"basis": "CT 355",
"url": "https://www.pgdlisboa.pt/leis/lei_mostra_articulado.php?artigo_id=1047A0355&nid=1047&tabela=leis",
"confidence": "verified",
"level": "red",
"values": {}
}
]
},
"protected": [],
"person_facts": {
"id": "p2",
"name": "Bea Silva",
"status": "active",
"title": "Agent",
"team": "Support",
"location": "Lisboa",
"country": "PT",
"contract_type": "open_ended",
"start": "2024-01-08",
"last_day": null
},
"events": [
{
"id": "e1",
"kind": "charges_delivered",
"label": "Nota de culpa delivered",
"date": "2026-11-18",
"received_on": "2026-11-20",
"due_on": null,
"ref": null,
"note": null,
"item_ids": [],
"by": {
"user_id": "u1",
"name": "Rui Lopes"
},
"at": "2026-11-21T10:00:00.000Z"
}
],
"items": [
{
"id": "i1",
"doc_no": "D-1",
"kind": "record",
"role": "evidence",
"label": "No record, 2026-11-03, scheduled 09:00–18:00",
"on": "2026-11-03",
"source": {
"module": "timeclock",
"type": "timeclock_no_record",
"ref": "no_record:2026-11-03",
"hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
},
"snapshot": {
"date": "2026-11-03",
"start": "09:00",
"end": "18:00"
},
"file": null,
"email": null,
"statement": null,
"confirmed": null,
"from_request": null,
"linked_by": {
"user_id": "u1",
"name": "Rui Lopes"
},
"linked_at": "2026-11-21T10:00:00.000Z",
"removed": null
}
],
"requests": [],
"counter": {
"year": 2026,
"total": 0,
"longest_run": 0,
"reaches": false,
"unconfirmed": 1
},
"allowed_events": [
"charges_delivered",
"defence_received",
"note"
],
"retention_until": null,
"me": {
"letters": true,
"answer": true,
"consult": true
},
"can": {
"edit": true,
"lead": true
},
"files": {
"count": 0,
"bytes": 0,
"max_files": 500,
"max_bytes": 2000000000
},
"bundle": {
"last": null,
"left_today": 10
},
"today": "2026-11-23"
}
}Turn an inquiry into a dismissal or sanction case#
POST/v1/relations/cases.convertWrite
Converts an open inquiry into a dismissal or sanction case; it keeps its file, events and dates (the inquiry's interruption of the limits stays, CT 352). The lead only. In the app only.
- Web app only
- Refused for API keys and connected apps. Employee relations works only in the Bizisy app: a case is confidential to its team.
- MCP tool
relations_cases_converton 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
case_idstringrequired1–64 characters.
kind"dismissal" | "sanction"required
Returns
36 fields
idstringrequirednumberstringrequiredkind"dismissal" | "sanction" | "abandonment" | "inquiry"requiredstatus"open" | "closed"requiredphasestring (enum)requiredOne of:
facts,inquiry,defence,evidence,opinion,decision,decided,applied,absence,letter_sent,closed.personobject | nullrequired2 fields
idstringrequirednamestringrequired
nextobject | nullrequired6 fields
labelstringrequiredbasisstringrequiredduestringrequireddays_leftintegerrequiredstate"waiting" | "running" | "ended" | "met" | "missed" | "info"requiredlapsebooleanrequired
lapsedbooleanrequiredholdbooleanrequiredteamobject[]required4 fields
user_idstringrequirednamestringrequiredrole"lead" | "member" | "decider" | "reviewer"requiredvia_break_glassbooleanrequired
my_role"lead" | "member" | "decider" | "reviewer"requirednull: a register row (owners and admins, not on the team).
opened_onstringrequiredclosed_atstring | nullrequiredoutcome"no_sanction" | "sanction" | "dismissal" | "dropped" | "resigned" | "abandonment"requiredpackobjectrequired7 fields
id"pt" | "es" | "eu"requiredversionstringrequirednamestringrequiredlegalbooleanrequirednotestringrequiredcurrent_versionstringrequirednewerbooleanrequired
countrystring | nullrequiredfactsobject[]required7 fields
idstringrequiredtitlestringrequireddatesstring[]requiredlearned_onstring | nullrequiredcrimebooleanrequiredcrime_untilstring | nullrequiredseverity"leve" | "grave" | "muy_grave"required
flagsobjectrequired9 fields
repbooleanrequiredunionbooleanrequiredcandidatebooleanrequiredmicrobooleanrequiredcouncilbooleanrequiredparentalbooleanrequiredcomplaint_onstring | nullrequiredequality_complaintbooleanrequiredwhistleblowerbooleanrequired
parental_from_timeoffbooleanrequiredabsent_sincestring | nullrequiredclocksobject[]required16 fields
keystringrequiredclockstringrequiredtype"deadline" | "wait" | "info"requiredfact_idstring | nullrequiredlabelstringrequiredEnglish; the app translates it.
basisstringrequiredThe article, untranslated: "CT 329(2)".
urlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredstopsstringrequiredif_missedstringrequiredlapsebooleanrequiredstarted_onstring | nullrequiredduestring | nullrequiredstate"waiting" | "running" | "ended" | "met" | "missed" | "info"requireddays_leftinteger | nullrequirednotestring | nullrequired
next3object[]required16 fields
keystringrequiredclockstringrequiredtype"deadline" | "wait" | "info"requiredfact_idstring | nullrequiredlabelstringrequiredEnglish; the app translates it.
basisstringrequiredThe article, untranslated: "CT 329(2)".
urlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredstopsstringrequiredif_missedstringrequiredlapsebooleanrequiredstarted_onstring | nullrequiredduestring | nullrequiredstate"waiting" | "running" | "ended" | "met" | "missed" | "info"requireddays_leftinteger | nullrequirednotestring | nullrequired
checksobjectrequired2 fields
chargesobject[]required7 fields
idstringrequiredmessagestringrequiredEnglish with {n}, {date}, {clock} filled from values.
basisstringrequiredurlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredlevel"red" | "warning" | "info"requiredvaluesobjectrequired
decisionobject[]required7 fields
idstringrequiredmessagestringrequiredEnglish with {n}, {date}, {clock} filled from values.
basisstringrequiredurlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredlevel"red" | "warning" | "info"requiredvaluesobjectrequired
protectedobject[]required7 fields
idstringrequiredmessagestringrequiredEnglish with {n}, {date}, {clock} filled from values.
basisstringrequiredurlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredlevel"red" | "warning" | "info"requiredvaluesobjectrequired
person_factsobject | nullrequired10 fields
idstringrequirednamestringrequiredstatusstringrequiredtitlestring | nullrequiredteamstring | nullrequiredlocationstring | nullrequiredcountrystring | nullrequiredcontract_typestring | nullrequiredstartstring | nullrequiredlast_daystring | nullrequired
eventsobject[]required11 fields
idstringrequiredkindstring (enum)requiredOne of:
inquiry_started,inquiry_ended,suspension_started,suspension_ended,charges_delivered,defence_extended,defence_received,union_named,evidence_requested,evidence_done,evidence_refused,hearing_offered,hearing_held,expediente_opened,file_to_council,opinion_received,cite_sent,cite_opinion,decision_delivered,sanction_applied,contact_recorded,registered_letter_sent,claim_filed,claim_ended,note,item_removed,converted,closed,reopened.labelstringrequireddatestringrequiredreceived_onstring | nullrequireddue_onstring | nullrequiredrefstring | nullrequirednotestring | nullrequireditem_idsstring[]requiredbyobjectrequired2 fields
user_idstringrequirednamestringrequired
atstringrequired
itemsobject[]required16 fields
idstringrequireddoc_nostringrequiredkind"record" | "file" | "statement"requiredrole"evidence" | "defence" | "statement" | "proof" | "opinion" | "other"requiredlabelstringrequiredonstring | nullrequiredsourceobject | nullrequired4 fields
modulestringrequiredtypestring (enum)requiredOne of:
timeclock_no_record,timeclock_late,timeoff,shifts,training_assigned,training_failed,documents,org_facts,earlier_case.refstringrequiredhashstringrequired
snapshotobject | nullrequiredfileobject | nullrequired6 fields
namestringrequiredcontent_typestringrequiredsizeintegerrequiredsha256string | nullrequiredpagesinteger | nullrequiredstatus"pending" | "ready"required
emailobject | nullrequired8 fields
fromstring | nullrequiredtostring | nullrequiredccstring | nullrequireddatestring | nullrequiredsubjectstring | nullrequiredtextstringrequiredtruncatedbooleanrequiredattachmentsobject[]required5 fields
indexintegerrequirednamestringrequiredcontent_typestringrequiredsizeintegerrequiredextracted_item_idstring | nullrequired
statementstring | nullrequiredconfirmed"unjustified" | "justified"requiredfrom_requestobject | nullrequired2 fields
request_idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
linked_byobjectrequired2 fields
user_idstringrequirednamestringrequired
linked_atstringrequiredremovedobject | nullrequired3 fields
atstringrequiredbystringrequiredreasonstring | nullrequired
requestsobject[]required8 fields
idstringrequiredtoobjectrequired2 fields
idstringrequirednamestringrequired
askstringrequiredduestring | nullrequiredstatus"open" | "answered" | "cancelled" | "expired"requiredanswered_atstring | nullrequireditem_idsstring[]requiredatstringrequired
counterobject | nullrequired5 fields
yearintegerrequiredtotalintegerrequiredlongest_runintegerrequiredreachesbooleanrequiredunconfirmedintegerrequired
allowed_eventsstring (enum)[]requiredOne of:
inquiry_started,inquiry_ended,suspension_started,suspension_ended,charges_delivered,defence_extended,defence_received,union_named,evidence_requested,evidence_done,evidence_refused,hearing_offered,hearing_held,expediente_opened,file_to_council,opinion_received,cite_sent,cite_opinion,decision_delivered,sanction_applied,contact_recorded,registered_letter_sent,claim_filed,claim_ended,note,item_removed,converted,closed,reopened.retention_untilstring | nullrequiredmeobjectrequired3 fields
lettersbooleanrequiredanswerbooleanrequiredconsultbooleanrequired
canobjectrequired2 fields
editbooleanrequiredleadbooleanrequired
filesobjectrequired4 fields
countintegerrequiredbytesintegerrequiredmax_filesintegerrequiredmax_bytesintegerrequired
bundleobjectrequired2 fields
lastobject | nullrequired2 fields
atstringrequiredpagesintegerrequired
left_todayintegerrequired
todaystringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/cases.convert \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"case_id":"c1","kind":"sanction"}'const res = await fetch('https://api.bizisy.com/v1/relations/cases.convert', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"case_id": "c1",
"kind": "sanction"
}),
});
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/relations/cases.convert",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"case_id": "c1",
"kind": "sanction",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "c1",
"number": "ER-2026-0001",
"kind": "sanction",
"status": "open",
"phase": "defence",
"person": {
"id": "p2",
"name": "Bea Silva"
},
"next": {
"label": "Defence period",
"basis": "CT 355(1)",
"due": "2026-12-07",
"days_left": 14,
"state": "running",
"lapse": false
},
"lapsed": false,
"hold": false,
"team": [
{
"user_id": "u1",
"name": "Rui Lopes",
"role": "lead",
"via_break_glass": false
}
],
"my_role": "lead",
"opened_on": "2026-11-05",
"closed_at": null,
"outcome": null,
"pack": {
"id": "pt",
"version": "2026-11-22",
"name": "Portugal: Código do Trabalho",
"legal": true,
"note": "Deadlines from the Código do Trabalho.",
"current_version": "2026-11-22",
"newer": false
},
"country": "PT",
"facts": [
{
"id": "f1",
"title": "Absent without notice",
"dates": [
"2026-11-03"
],
"learned_on": "2026-11-05",
"crime": false,
"crime_until": null,
"severity": null
}
],
"flags": {
"rep": false,
"union": false,
"candidate": false,
"micro": false,
"council": false,
"parental": false,
"complaint_on": null,
"equality_complaint": false,
"whistleblower": false
},
"parental_from_timeoff": false,
"absent_since": null,
"clocks": [
{
"key": "C6",
"clock": "C6",
"type": "wait",
"fact_id": null,
"label": "Defence period",
"basis": "CT 355(1)",
"url": "https://www.pgdlisboa.pt/leis/lei_mostra_articulado.php?artigo_id=1047A0355&nid=1047&tabela=leis",
"confidence": "verified",
"stops": "The answer received early, or an extension the team grants (recorded)",
"if_missed": "The team may go on with the procedure.",
"lapse": false,
"started_on": "2026-11-20",
"due": "2026-12-07",
"state": "running",
"days_left": 14,
"note": null
}
],
"next3": [
{
"key": "C6",
"clock": "C6",
"type": "wait",
"fact_id": null,
"label": "Defence period",
"basis": "CT 355(1)",
"url": "https://www.pgdlisboa.pt/leis/lei_mostra_articulado.php?artigo_id=1047A0355&nid=1047&tabela=leis",
"confidence": "verified",
"stops": "The answer received early, or an extension the team grants (recorded)",
"if_missed": "The team may go on with the procedure.",
"lapse": false,
"started_on": "2026-11-20",
"due": "2026-12-07",
"state": "running",
"days_left": 14,
"note": null
}
],
"checks": {
"charges": [],
"decision": [
{
"id": "defence_open",
"message": "The defence period isn't over.",
"basis": "CT 355",
"url": "https://www.pgdlisboa.pt/leis/lei_mostra_articulado.php?artigo_id=1047A0355&nid=1047&tabela=leis",
"confidence": "verified",
"level": "red",
"values": {}
}
]
},
"protected": [],
"person_facts": {
"id": "p2",
"name": "Bea Silva",
"status": "active",
"title": "Agent",
"team": "Support",
"location": "Lisboa",
"country": "PT",
"contract_type": "open_ended",
"start": "2024-01-08",
"last_day": null
},
"events": [
{
"id": "e1",
"kind": "charges_delivered",
"label": "Nota de culpa delivered",
"date": "2026-11-18",
"received_on": "2026-11-20",
"due_on": null,
"ref": null,
"note": null,
"item_ids": [],
"by": {
"user_id": "u1",
"name": "Rui Lopes"
},
"at": "2026-11-21T10:00:00.000Z"
}
],
"items": [
{
"id": "i1",
"doc_no": "D-1",
"kind": "record",
"role": "evidence",
"label": "No record, 2026-11-03, scheduled 09:00–18:00",
"on": "2026-11-03",
"source": {
"module": "timeclock",
"type": "timeclock_no_record",
"ref": "no_record:2026-11-03",
"hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
},
"snapshot": {
"date": "2026-11-03",
"start": "09:00",
"end": "18:00"
},
"file": null,
"email": null,
"statement": null,
"confirmed": null,
"from_request": null,
"linked_by": {
"user_id": "u1",
"name": "Rui Lopes"
},
"linked_at": "2026-11-21T10:00:00.000Z",
"removed": null
}
],
"requests": [],
"counter": {
"year": 2026,
"total": 0,
"longest_run": 0,
"reaches": false,
"unconfirmed": 1
},
"allowed_events": [
"charges_delivered",
"defence_received",
"note"
],
"retention_until": null,
"me": {
"letters": true,
"answer": true,
"consult": true
},
"can": {
"edit": true,
"lead": true
},
"files": {
"count": 0,
"bytes": 0,
"max_files": 500,
"max_bytes": 2000000000
},
"bundle": {
"last": null,
"left_today": 10
},
"today": "2026-11-23"
}
}Close a case#
POST/v1/relations/cases.closeWrite
Closes an open case with its outcome (no_sanction, sanction, dismissal, dropped, resigned, abandonment) and sets how long it is kept (E9: dismissal and abandonment 1 year and 3 months after the employment ends; a sanction while employed at most 5 years after the decision, 1 year after the employment ends; no sanction 1 year after closing; the company may change these in Settings within the law's range). A case on legal hold is kept until the claim ends. The lead only. A dry run shows the retention date. In the app only.
- Web app only
- Refused for API keys and connected apps. Employee relations works only in the Bizisy app: a case is confidential to its team.
- MCP tool
relations_cases_closeon 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
case_idstringrequired1–64 characters.
outcome"no_sanction" | "sanction" | "dismissal" | "dropped" | "resigned" | "abandonment"requirednotestring | nullUp to 2000 characters. Default
null.
Returns
36 fields
idstringrequirednumberstringrequiredkind"dismissal" | "sanction" | "abandonment" | "inquiry"requiredstatus"open" | "closed"requiredphasestring (enum)requiredOne of:
facts,inquiry,defence,evidence,opinion,decision,decided,applied,absence,letter_sent,closed.personobject | nullrequired2 fields
idstringrequirednamestringrequired
nextobject | nullrequired6 fields
labelstringrequiredbasisstringrequiredduestringrequireddays_leftintegerrequiredstate"waiting" | "running" | "ended" | "met" | "missed" | "info"requiredlapsebooleanrequired
lapsedbooleanrequiredholdbooleanrequiredteamobject[]required4 fields
user_idstringrequirednamestringrequiredrole"lead" | "member" | "decider" | "reviewer"requiredvia_break_glassbooleanrequired
my_role"lead" | "member" | "decider" | "reviewer"requirednull: a register row (owners and admins, not on the team).
opened_onstringrequiredclosed_atstring | nullrequiredoutcome"no_sanction" | "sanction" | "dismissal" | "dropped" | "resigned" | "abandonment"requiredpackobjectrequired7 fields
id"pt" | "es" | "eu"requiredversionstringrequirednamestringrequiredlegalbooleanrequirednotestringrequiredcurrent_versionstringrequirednewerbooleanrequired
countrystring | nullrequiredfactsobject[]required7 fields
idstringrequiredtitlestringrequireddatesstring[]requiredlearned_onstring | nullrequiredcrimebooleanrequiredcrime_untilstring | nullrequiredseverity"leve" | "grave" | "muy_grave"required
flagsobjectrequired9 fields
repbooleanrequiredunionbooleanrequiredcandidatebooleanrequiredmicrobooleanrequiredcouncilbooleanrequiredparentalbooleanrequiredcomplaint_onstring | nullrequiredequality_complaintbooleanrequiredwhistleblowerbooleanrequired
parental_from_timeoffbooleanrequiredabsent_sincestring | nullrequiredclocksobject[]required16 fields
keystringrequiredclockstringrequiredtype"deadline" | "wait" | "info"requiredfact_idstring | nullrequiredlabelstringrequiredEnglish; the app translates it.
basisstringrequiredThe article, untranslated: "CT 329(2)".
urlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredstopsstringrequiredif_missedstringrequiredlapsebooleanrequiredstarted_onstring | nullrequiredduestring | nullrequiredstate"waiting" | "running" | "ended" | "met" | "missed" | "info"requireddays_leftinteger | nullrequirednotestring | nullrequired
next3object[]required16 fields
keystringrequiredclockstringrequiredtype"deadline" | "wait" | "info"requiredfact_idstring | nullrequiredlabelstringrequiredEnglish; the app translates it.
basisstringrequiredThe article, untranslated: "CT 329(2)".
urlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredstopsstringrequiredif_missedstringrequiredlapsebooleanrequiredstarted_onstring | nullrequiredduestring | nullrequiredstate"waiting" | "running" | "ended" | "met" | "missed" | "info"requireddays_leftinteger | nullrequirednotestring | nullrequired
checksobjectrequired2 fields
chargesobject[]required7 fields
idstringrequiredmessagestringrequiredEnglish with {n}, {date}, {clock} filled from values.
basisstringrequiredurlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredlevel"red" | "warning" | "info"requiredvaluesobjectrequired
decisionobject[]required7 fields
idstringrequiredmessagestringrequiredEnglish with {n}, {date}, {clock} filled from values.
basisstringrequiredurlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredlevel"red" | "warning" | "info"requiredvaluesobjectrequired
protectedobject[]required7 fields
idstringrequiredmessagestringrequiredEnglish with {n}, {date}, {clock} filled from values.
basisstringrequiredurlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredlevel"red" | "warning" | "info"requiredvaluesobjectrequired
person_factsobject | nullrequired10 fields
idstringrequirednamestringrequiredstatusstringrequiredtitlestring | nullrequiredteamstring | nullrequiredlocationstring | nullrequiredcountrystring | nullrequiredcontract_typestring | nullrequiredstartstring | nullrequiredlast_daystring | nullrequired
eventsobject[]required11 fields
idstringrequiredkindstring (enum)requiredOne of:
inquiry_started,inquiry_ended,suspension_started,suspension_ended,charges_delivered,defence_extended,defence_received,union_named,evidence_requested,evidence_done,evidence_refused,hearing_offered,hearing_held,expediente_opened,file_to_council,opinion_received,cite_sent,cite_opinion,decision_delivered,sanction_applied,contact_recorded,registered_letter_sent,claim_filed,claim_ended,note,item_removed,converted,closed,reopened.labelstringrequireddatestringrequiredreceived_onstring | nullrequireddue_onstring | nullrequiredrefstring | nullrequirednotestring | nullrequireditem_idsstring[]requiredbyobjectrequired2 fields
user_idstringrequirednamestringrequired
atstringrequired
itemsobject[]required16 fields
idstringrequireddoc_nostringrequiredkind"record" | "file" | "statement"requiredrole"evidence" | "defence" | "statement" | "proof" | "opinion" | "other"requiredlabelstringrequiredonstring | nullrequiredsourceobject | nullrequired4 fields
modulestringrequiredtypestring (enum)requiredOne of:
timeclock_no_record,timeclock_late,timeoff,shifts,training_assigned,training_failed,documents,org_facts,earlier_case.refstringrequiredhashstringrequired
snapshotobject | nullrequiredfileobject | nullrequired6 fields
namestringrequiredcontent_typestringrequiredsizeintegerrequiredsha256string | nullrequiredpagesinteger | nullrequiredstatus"pending" | "ready"required
emailobject | nullrequired8 fields
fromstring | nullrequiredtostring | nullrequiredccstring | nullrequireddatestring | nullrequiredsubjectstring | nullrequiredtextstringrequiredtruncatedbooleanrequiredattachmentsobject[]required5 fields
indexintegerrequirednamestringrequiredcontent_typestringrequiredsizeintegerrequiredextracted_item_idstring | nullrequired
statementstring | nullrequiredconfirmed"unjustified" | "justified"requiredfrom_requestobject | nullrequired2 fields
request_idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
linked_byobjectrequired2 fields
user_idstringrequirednamestringrequired
linked_atstringrequiredremovedobject | nullrequired3 fields
atstringrequiredbystringrequiredreasonstring | nullrequired
requestsobject[]required8 fields
idstringrequiredtoobjectrequired2 fields
idstringrequirednamestringrequired
askstringrequiredduestring | nullrequiredstatus"open" | "answered" | "cancelled" | "expired"requiredanswered_atstring | nullrequireditem_idsstring[]requiredatstringrequired
counterobject | nullrequired5 fields
yearintegerrequiredtotalintegerrequiredlongest_runintegerrequiredreachesbooleanrequiredunconfirmedintegerrequired
allowed_eventsstring (enum)[]requiredOne of:
inquiry_started,inquiry_ended,suspension_started,suspension_ended,charges_delivered,defence_extended,defence_received,union_named,evidence_requested,evidence_done,evidence_refused,hearing_offered,hearing_held,expediente_opened,file_to_council,opinion_received,cite_sent,cite_opinion,decision_delivered,sanction_applied,contact_recorded,registered_letter_sent,claim_filed,claim_ended,note,item_removed,converted,closed,reopened.retention_untilstring | nullrequiredmeobjectrequired3 fields
lettersbooleanrequiredanswerbooleanrequiredconsultbooleanrequired
canobjectrequired2 fields
editbooleanrequiredleadbooleanrequired
filesobjectrequired4 fields
countintegerrequiredbytesintegerrequiredmax_filesintegerrequiredmax_bytesintegerrequired
bundleobjectrequired2 fields
lastobject | nullrequired2 fields
atstringrequiredpagesintegerrequired
left_todayintegerrequired
todaystringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/cases.close \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"case_id":"c1","outcome":"no_sanction"}'const res = await fetch('https://api.bizisy.com/v1/relations/cases.close', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"case_id": "c1",
"outcome": "no_sanction"
}),
});
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/relations/cases.close",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"case_id": "c1",
"outcome": "no_sanction",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "c1",
"number": "ER-2026-0001",
"kind": "dismissal",
"status": "closed",
"phase": "closed",
"person": {
"id": "p2",
"name": "Bea Silva"
},
"next": {
"label": "Defence period",
"basis": "CT 355(1)",
"due": "2026-12-07",
"days_left": 14,
"state": "running",
"lapse": false
},
"lapsed": false,
"hold": false,
"team": [
{
"user_id": "u1",
"name": "Rui Lopes",
"role": "lead",
"via_break_glass": false
}
],
"my_role": "lead",
"opened_on": "2026-11-05",
"closed_at": "2026-11-23T10:00:00.000Z",
"outcome": "no_sanction",
"pack": {
"id": "pt",
"version": "2026-11-22",
"name": "Portugal: Código do Trabalho",
"legal": true,
"note": "Deadlines from the Código do Trabalho.",
"current_version": "2026-11-22",
"newer": false
},
"country": "PT",
"facts": [
{
"id": "f1",
"title": "Absent without notice",
"dates": [
"2026-11-03"
],
"learned_on": "2026-11-05",
"crime": false,
"crime_until": null,
"severity": null
}
],
"flags": {
"rep": false,
"union": false,
"candidate": false,
"micro": false,
"council": false,
"parental": false,
"complaint_on": null,
"equality_complaint": false,
"whistleblower": false
},
"parental_from_timeoff": false,
"absent_since": null,
"clocks": [
{
"key": "C6",
"clock": "C6",
"type": "wait",
"fact_id": null,
"label": "Defence period",
"basis": "CT 355(1)",
"url": "https://www.pgdlisboa.pt/leis/lei_mostra_articulado.php?artigo_id=1047A0355&nid=1047&tabela=leis",
"confidence": "verified",
"stops": "The answer received early, or an extension the team grants (recorded)",
"if_missed": "The team may go on with the procedure.",
"lapse": false,
"started_on": "2026-11-20",
"due": "2026-12-07",
"state": "running",
"days_left": 14,
"note": null
}
],
"next3": [
{
"key": "C6",
"clock": "C6",
"type": "wait",
"fact_id": null,
"label": "Defence period",
"basis": "CT 355(1)",
"url": "https://www.pgdlisboa.pt/leis/lei_mostra_articulado.php?artigo_id=1047A0355&nid=1047&tabela=leis",
"confidence": "verified",
"stops": "The answer received early, or an extension the team grants (recorded)",
"if_missed": "The team may go on with the procedure.",
"lapse": false,
"started_on": "2026-11-20",
"due": "2026-12-07",
"state": "running",
"days_left": 14,
"note": null
}
],
"checks": {
"charges": [],
"decision": [
{
"id": "defence_open",
"message": "The defence period isn't over.",
"basis": "CT 355",
"url": "https://www.pgdlisboa.pt/leis/lei_mostra_articulado.php?artigo_id=1047A0355&nid=1047&tabela=leis",
"confidence": "verified",
"level": "red",
"values": {}
}
]
},
"protected": [],
"person_facts": {
"id": "p2",
"name": "Bea Silva",
"status": "active",
"title": "Agent",
"team": "Support",
"location": "Lisboa",
"country": "PT",
"contract_type": "open_ended",
"start": "2024-01-08",
"last_day": null
},
"events": [
{
"id": "e1",
"kind": "charges_delivered",
"label": "Nota de culpa delivered",
"date": "2026-11-18",
"received_on": "2026-11-20",
"due_on": null,
"ref": null,
"note": null,
"item_ids": [],
"by": {
"user_id": "u1",
"name": "Rui Lopes"
},
"at": "2026-11-21T10:00:00.000Z"
}
],
"items": [
{
"id": "i1",
"doc_no": "D-1",
"kind": "record",
"role": "evidence",
"label": "No record, 2026-11-03, scheduled 09:00–18:00",
"on": "2026-11-03",
"source": {
"module": "timeclock",
"type": "timeclock_no_record",
"ref": "no_record:2026-11-03",
"hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
},
"snapshot": {
"date": "2026-11-03",
"start": "09:00",
"end": "18:00"
},
"file": null,
"email": null,
"statement": null,
"confirmed": null,
"from_request": null,
"linked_by": {
"user_id": "u1",
"name": "Rui Lopes"
},
"linked_at": "2026-11-21T10:00:00.000Z",
"removed": null
}
],
"requests": [],
"counter": {
"year": 2026,
"total": 0,
"longest_run": 0,
"reaches": false,
"unconfirmed": 1
},
"allowed_events": [
"charges_delivered",
"defence_received",
"note"
],
"retention_until": "2027-11-23",
"me": {
"letters": true,
"answer": true,
"consult": true
},
"can": {
"edit": true,
"lead": true
},
"files": {
"count": 0,
"bytes": 0,
"max_files": 500,
"max_bytes": 2000000000
},
"bundle": {
"last": null,
"left_today": 10
},
"today": "2026-11-23"
}
}Reopen a closed case#
POST/v1/relations/cases.reopenWrite
Reopens a closed case (closed by mistake, or new facts): its retention date is cleared until it closes again. The lead only. In the app only.
- Web app only
- Refused for API keys and connected apps. Employee relations works only in the Bizisy app: a case is confidential to its team.
- MCP tool
relations_cases_reopenon 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
case_idstringrequired1–64 characters.
Returns
36 fields
idstringrequirednumberstringrequiredkind"dismissal" | "sanction" | "abandonment" | "inquiry"requiredstatus"open" | "closed"requiredphasestring (enum)requiredOne of:
facts,inquiry,defence,evidence,opinion,decision,decided,applied,absence,letter_sent,closed.personobject | nullrequired2 fields
idstringrequirednamestringrequired
nextobject | nullrequired6 fields
labelstringrequiredbasisstringrequiredduestringrequireddays_leftintegerrequiredstate"waiting" | "running" | "ended" | "met" | "missed" | "info"requiredlapsebooleanrequired
lapsedbooleanrequiredholdbooleanrequiredteamobject[]required4 fields
user_idstringrequirednamestringrequiredrole"lead" | "member" | "decider" | "reviewer"requiredvia_break_glassbooleanrequired
my_role"lead" | "member" | "decider" | "reviewer"requirednull: a register row (owners and admins, not on the team).
opened_onstringrequiredclosed_atstring | nullrequiredoutcome"no_sanction" | "sanction" | "dismissal" | "dropped" | "resigned" | "abandonment"requiredpackobjectrequired7 fields
id"pt" | "es" | "eu"requiredversionstringrequirednamestringrequiredlegalbooleanrequirednotestringrequiredcurrent_versionstringrequirednewerbooleanrequired
countrystring | nullrequiredfactsobject[]required7 fields
idstringrequiredtitlestringrequireddatesstring[]requiredlearned_onstring | nullrequiredcrimebooleanrequiredcrime_untilstring | nullrequiredseverity"leve" | "grave" | "muy_grave"required
flagsobjectrequired9 fields
repbooleanrequiredunionbooleanrequiredcandidatebooleanrequiredmicrobooleanrequiredcouncilbooleanrequiredparentalbooleanrequiredcomplaint_onstring | nullrequiredequality_complaintbooleanrequiredwhistleblowerbooleanrequired
parental_from_timeoffbooleanrequiredabsent_sincestring | nullrequiredclocksobject[]required16 fields
keystringrequiredclockstringrequiredtype"deadline" | "wait" | "info"requiredfact_idstring | nullrequiredlabelstringrequiredEnglish; the app translates it.
basisstringrequiredThe article, untranslated: "CT 329(2)".
urlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredstopsstringrequiredif_missedstringrequiredlapsebooleanrequiredstarted_onstring | nullrequiredduestring | nullrequiredstate"waiting" | "running" | "ended" | "met" | "missed" | "info"requireddays_leftinteger | nullrequirednotestring | nullrequired
next3object[]required16 fields
keystringrequiredclockstringrequiredtype"deadline" | "wait" | "info"requiredfact_idstring | nullrequiredlabelstringrequiredEnglish; the app translates it.
basisstringrequiredThe article, untranslated: "CT 329(2)".
urlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredstopsstringrequiredif_missedstringrequiredlapsebooleanrequiredstarted_onstring | nullrequiredduestring | nullrequiredstate"waiting" | "running" | "ended" | "met" | "missed" | "info"requireddays_leftinteger | nullrequirednotestring | nullrequired
checksobjectrequired2 fields
chargesobject[]required7 fields
idstringrequiredmessagestringrequiredEnglish with {n}, {date}, {clock} filled from values.
basisstringrequiredurlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredlevel"red" | "warning" | "info"requiredvaluesobjectrequired
decisionobject[]required7 fields
idstringrequiredmessagestringrequiredEnglish with {n}, {date}, {clock} filled from values.
basisstringrequiredurlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredlevel"red" | "warning" | "info"requiredvaluesobjectrequired
protectedobject[]required7 fields
idstringrequiredmessagestringrequiredEnglish with {n}, {date}, {clock} filled from values.
basisstringrequiredurlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredlevel"red" | "warning" | "info"requiredvaluesobjectrequired
person_factsobject | nullrequired10 fields
idstringrequirednamestringrequiredstatusstringrequiredtitlestring | nullrequiredteamstring | nullrequiredlocationstring | nullrequiredcountrystring | nullrequiredcontract_typestring | nullrequiredstartstring | nullrequiredlast_daystring | nullrequired
eventsobject[]required11 fields
idstringrequiredkindstring (enum)requiredOne of:
inquiry_started,inquiry_ended,suspension_started,suspension_ended,charges_delivered,defence_extended,defence_received,union_named,evidence_requested,evidence_done,evidence_refused,hearing_offered,hearing_held,expediente_opened,file_to_council,opinion_received,cite_sent,cite_opinion,decision_delivered,sanction_applied,contact_recorded,registered_letter_sent,claim_filed,claim_ended,note,item_removed,converted,closed,reopened.labelstringrequireddatestringrequiredreceived_onstring | nullrequireddue_onstring | nullrequiredrefstring | nullrequirednotestring | nullrequireditem_idsstring[]requiredbyobjectrequired2 fields
user_idstringrequirednamestringrequired
atstringrequired
itemsobject[]required16 fields
idstringrequireddoc_nostringrequiredkind"record" | "file" | "statement"requiredrole"evidence" | "defence" | "statement" | "proof" | "opinion" | "other"requiredlabelstringrequiredonstring | nullrequiredsourceobject | nullrequired4 fields
modulestringrequiredtypestring (enum)requiredOne of:
timeclock_no_record,timeclock_late,timeoff,shifts,training_assigned,training_failed,documents,org_facts,earlier_case.refstringrequiredhashstringrequired
snapshotobject | nullrequiredfileobject | nullrequired6 fields
namestringrequiredcontent_typestringrequiredsizeintegerrequiredsha256string | nullrequiredpagesinteger | nullrequiredstatus"pending" | "ready"required
emailobject | nullrequired8 fields
fromstring | nullrequiredtostring | nullrequiredccstring | nullrequireddatestring | nullrequiredsubjectstring | nullrequiredtextstringrequiredtruncatedbooleanrequiredattachmentsobject[]required5 fields
indexintegerrequirednamestringrequiredcontent_typestringrequiredsizeintegerrequiredextracted_item_idstring | nullrequired
statementstring | nullrequiredconfirmed"unjustified" | "justified"requiredfrom_requestobject | nullrequired2 fields
request_idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
linked_byobjectrequired2 fields
user_idstringrequirednamestringrequired
linked_atstringrequiredremovedobject | nullrequired3 fields
atstringrequiredbystringrequiredreasonstring | nullrequired
requestsobject[]required8 fields
idstringrequiredtoobjectrequired2 fields
idstringrequirednamestringrequired
askstringrequiredduestring | nullrequiredstatus"open" | "answered" | "cancelled" | "expired"requiredanswered_atstring | nullrequireditem_idsstring[]requiredatstringrequired
counterobject | nullrequired5 fields
yearintegerrequiredtotalintegerrequiredlongest_runintegerrequiredreachesbooleanrequiredunconfirmedintegerrequired
allowed_eventsstring (enum)[]requiredOne of:
inquiry_started,inquiry_ended,suspension_started,suspension_ended,charges_delivered,defence_extended,defence_received,union_named,evidence_requested,evidence_done,evidence_refused,hearing_offered,hearing_held,expediente_opened,file_to_council,opinion_received,cite_sent,cite_opinion,decision_delivered,sanction_applied,contact_recorded,registered_letter_sent,claim_filed,claim_ended,note,item_removed,converted,closed,reopened.retention_untilstring | nullrequiredmeobjectrequired3 fields
lettersbooleanrequiredanswerbooleanrequiredconsultbooleanrequired
canobjectrequired2 fields
editbooleanrequiredleadbooleanrequired
filesobjectrequired4 fields
countintegerrequiredbytesintegerrequiredmax_filesintegerrequiredmax_bytesintegerrequired
bundleobjectrequired2 fields
lastobject | nullrequired2 fields
atstringrequiredpagesintegerrequired
left_todayintegerrequired
todaystringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/cases.reopen \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"case_id":"c1"}'const res = await fetch('https://api.bizisy.com/v1/relations/cases.reopen', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"case_id": "c1"
}),
});
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/relations/cases.reopen",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"case_id": "c1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "c1",
"number": "ER-2026-0001",
"kind": "dismissal",
"status": "open",
"phase": "defence",
"person": {
"id": "p2",
"name": "Bea Silva"
},
"next": {
"label": "Defence period",
"basis": "CT 355(1)",
"due": "2026-12-07",
"days_left": 14,
"state": "running",
"lapse": false
},
"lapsed": false,
"hold": false,
"team": [
{
"user_id": "u1",
"name": "Rui Lopes",
"role": "lead",
"via_break_glass": false
}
],
"my_role": "lead",
"opened_on": "2026-11-05",
"closed_at": null,
"outcome": null,
"pack": {
"id": "pt",
"version": "2026-11-22",
"name": "Portugal: Código do Trabalho",
"legal": true,
"note": "Deadlines from the Código do Trabalho.",
"current_version": "2026-11-22",
"newer": false
},
"country": "PT",
"facts": [
{
"id": "f1",
"title": "Absent without notice",
"dates": [
"2026-11-03"
],
"learned_on": "2026-11-05",
"crime": false,
"crime_until": null,
"severity": null
}
],
"flags": {
"rep": false,
"union": false,
"candidate": false,
"micro": false,
"council": false,
"parental": false,
"complaint_on": null,
"equality_complaint": false,
"whistleblower": false
},
"parental_from_timeoff": false,
"absent_since": null,
"clocks": [
{
"key": "C6",
"clock": "C6",
"type": "wait",
"fact_id": null,
"label": "Defence period",
"basis": "CT 355(1)",
"url": "https://www.pgdlisboa.pt/leis/lei_mostra_articulado.php?artigo_id=1047A0355&nid=1047&tabela=leis",
"confidence": "verified",
"stops": "The answer received early, or an extension the team grants (recorded)",
"if_missed": "The team may go on with the procedure.",
"lapse": false,
"started_on": "2026-11-20",
"due": "2026-12-07",
"state": "running",
"days_left": 14,
"note": null
}
],
"next3": [
{
"key": "C6",
"clock": "C6",
"type": "wait",
"fact_id": null,
"label": "Defence period",
"basis": "CT 355(1)",
"url": "https://www.pgdlisboa.pt/leis/lei_mostra_articulado.php?artigo_id=1047A0355&nid=1047&tabela=leis",
"confidence": "verified",
"stops": "The answer received early, or an extension the team grants (recorded)",
"if_missed": "The team may go on with the procedure.",
"lapse": false,
"started_on": "2026-11-20",
"due": "2026-12-07",
"state": "running",
"days_left": 14,
"note": null
}
],
"checks": {
"charges": [],
"decision": [
{
"id": "defence_open",
"message": "The defence period isn't over.",
"basis": "CT 355",
"url": "https://www.pgdlisboa.pt/leis/lei_mostra_articulado.php?artigo_id=1047A0355&nid=1047&tabela=leis",
"confidence": "verified",
"level": "red",
"values": {}
}
]
},
"protected": [],
"person_facts": {
"id": "p2",
"name": "Bea Silva",
"status": "active",
"title": "Agent",
"team": "Support",
"location": "Lisboa",
"country": "PT",
"contract_type": "open_ended",
"start": "2024-01-08",
"last_day": null
},
"events": [
{
"id": "e1",
"kind": "charges_delivered",
"label": "Nota de culpa delivered",
"date": "2026-11-18",
"received_on": "2026-11-20",
"due_on": null,
"ref": null,
"note": null,
"item_ids": [],
"by": {
"user_id": "u1",
"name": "Rui Lopes"
},
"at": "2026-11-21T10:00:00.000Z"
}
],
"items": [
{
"id": "i1",
"doc_no": "D-1",
"kind": "record",
"role": "evidence",
"label": "No record, 2026-11-03, scheduled 09:00–18:00",
"on": "2026-11-03",
"source": {
"module": "timeclock",
"type": "timeclock_no_record",
"ref": "no_record:2026-11-03",
"hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
},
"snapshot": {
"date": "2026-11-03",
"start": "09:00",
"end": "18:00"
},
"file": null,
"email": null,
"statement": null,
"confirmed": null,
"from_request": null,
"linked_by": {
"user_id": "u1",
"name": "Rui Lopes"
},
"linked_at": "2026-11-21T10:00:00.000Z",
"removed": null
}
],
"requests": [],
"counter": {
"year": 2026,
"total": 0,
"longest_run": 0,
"reaches": false,
"unconfirmed": 1
},
"allowed_events": [
"charges_delivered",
"defence_received",
"note"
],
"retention_until": null,
"me": {
"letters": true,
"answer": true,
"consult": true
},
"can": {
"edit": true,
"lead": true
},
"files": {
"count": 0,
"bytes": 0,
"max_files": 500,
"max_bytes": 2000000000
},
"bundle": {
"last": null,
"left_today": 10
},
"today": "2026-11-23"
}
}Find the person a new case is about#
POST/v1/relations/people.searchRead
For ER staff opening a case, or a case team asking someone for evidence: people employed today whose name matches q (at most 20), with title and team, never yourself. In the app only.
- Web app only
- Refused for API keys and connected apps. Employee relations works only in the Bizisy app: a case is confidential to its team.
- MCP tool
relations_people_searchon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
qstringUp to 80 characters. Default
"".
Returns
peopleobject[]required4 fields
idstringrequirednamestringrequiredtitlestring | nullrequiredteamstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/people.search \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"q":"bea"}'const res = await fetch('https://api.bizisy.com/v1/relations/people.search', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"q": "bea"
}),
});
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/relations/people.search",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"q": "bea",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"people": [
{
"id": "p2",
"name": "Bea Silva",
"title": "Agent",
"team": "Support"
}
]
}
}Find people to put on a case team#
POST/v1/relations/members.searchRead
For ER staff, a case lead or owners and admins: logins that can work in Manage (owners, admins, HR, custom roles) whose name or email matches q (at most 20), with whether they are ER staff and, given person_id, whether they manage that person (they would see the whole case). In the app only.
- Web app only
- Refused for API keys and connected apps. Employee relations works only in the Bizisy app: a case is confidential to its team.
- MCP tool
relations_members_searchon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
qstringUp to 80 characters. Default
"".person_idstring1–64 characters.
Returns
membersobject[]required5 fields
user_idstringrequirednamestringrequiredemailstringrequiredstaffbooleanrequiredmanagesbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/members.search \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"q":"marta","person_id":"p2"}'const res = await fetch('https://api.bizisy.com/v1/relations/members.search', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"q": "marta",
"person_id": "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/relations/members.search",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"q": "marta",
"person_id": "p2",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"members": [
{
"user_id": "u2",
"name": "Marta Dias",
"email": "marta@acme.example",
"staff": false,
"manages": false
}
]
}
}Set a case's team#
POST/v1/relations/team.setWrite
Sets who is on the case and in which role (at most 20): exactly one lead (runs it; may hand it over), members (work on the file), a decider (the person with disciplinary power, CT 329(4); may be outside HR) and reviewers (read-only, e.g. in-house counsel). Everyone must be able to work in Manage; the person the case is about never. Someone who manages the person sees the whole case: confirm_chain after the warning, or send them an evidence request instead. The lead only. In the app only.
- Web app only
- Refused for API keys and connected apps. Employee relations works only in the Bizisy app: a case is confidential to its team.
- MCP tool
relations_team_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
case_idstringrequired1–64 characters.
teamobject[]required1–20 items.
2 fields
user_idstringrequired1–64 characters.
role"lead" | "member" | "decider" | "reviewer"required
confirm_chainbooleanDefault
false.
Returns
36 fields
idstringrequirednumberstringrequiredkind"dismissal" | "sanction" | "abandonment" | "inquiry"requiredstatus"open" | "closed"requiredphasestring (enum)requiredOne of:
facts,inquiry,defence,evidence,opinion,decision,decided,applied,absence,letter_sent,closed.personobject | nullrequired2 fields
idstringrequirednamestringrequired
nextobject | nullrequired6 fields
labelstringrequiredbasisstringrequiredduestringrequireddays_leftintegerrequiredstate"waiting" | "running" | "ended" | "met" | "missed" | "info"requiredlapsebooleanrequired
lapsedbooleanrequiredholdbooleanrequiredteamobject[]required4 fields
user_idstringrequirednamestringrequiredrole"lead" | "member" | "decider" | "reviewer"requiredvia_break_glassbooleanrequired
my_role"lead" | "member" | "decider" | "reviewer"requirednull: a register row (owners and admins, not on the team).
opened_onstringrequiredclosed_atstring | nullrequiredoutcome"no_sanction" | "sanction" | "dismissal" | "dropped" | "resigned" | "abandonment"requiredpackobjectrequired7 fields
id"pt" | "es" | "eu"requiredversionstringrequirednamestringrequiredlegalbooleanrequirednotestringrequiredcurrent_versionstringrequirednewerbooleanrequired
countrystring | nullrequiredfactsobject[]required7 fields
idstringrequiredtitlestringrequireddatesstring[]requiredlearned_onstring | nullrequiredcrimebooleanrequiredcrime_untilstring | nullrequiredseverity"leve" | "grave" | "muy_grave"required
flagsobjectrequired9 fields
repbooleanrequiredunionbooleanrequiredcandidatebooleanrequiredmicrobooleanrequiredcouncilbooleanrequiredparentalbooleanrequiredcomplaint_onstring | nullrequiredequality_complaintbooleanrequiredwhistleblowerbooleanrequired
parental_from_timeoffbooleanrequiredabsent_sincestring | nullrequiredclocksobject[]required16 fields
keystringrequiredclockstringrequiredtype"deadline" | "wait" | "info"requiredfact_idstring | nullrequiredlabelstringrequiredEnglish; the app translates it.
basisstringrequiredThe article, untranslated: "CT 329(2)".
urlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredstopsstringrequiredif_missedstringrequiredlapsebooleanrequiredstarted_onstring | nullrequiredduestring | nullrequiredstate"waiting" | "running" | "ended" | "met" | "missed" | "info"requireddays_leftinteger | nullrequirednotestring | nullrequired
next3object[]required16 fields
keystringrequiredclockstringrequiredtype"deadline" | "wait" | "info"requiredfact_idstring | nullrequiredlabelstringrequiredEnglish; the app translates it.
basisstringrequiredThe article, untranslated: "CT 329(2)".
urlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredstopsstringrequiredif_missedstringrequiredlapsebooleanrequiredstarted_onstring | nullrequiredduestring | nullrequiredstate"waiting" | "running" | "ended" | "met" | "missed" | "info"requireddays_leftinteger | nullrequirednotestring | nullrequired
checksobjectrequired2 fields
chargesobject[]required7 fields
idstringrequiredmessagestringrequiredEnglish with {n}, {date}, {clock} filled from values.
basisstringrequiredurlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredlevel"red" | "warning" | "info"requiredvaluesobjectrequired
decisionobject[]required7 fields
idstringrequiredmessagestringrequiredEnglish with {n}, {date}, {clock} filled from values.
basisstringrequiredurlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredlevel"red" | "warning" | "info"requiredvaluesobjectrequired
protectedobject[]required7 fields
idstringrequiredmessagestringrequiredEnglish with {n}, {date}, {clock} filled from values.
basisstringrequiredurlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredlevel"red" | "warning" | "info"requiredvaluesobjectrequired
person_factsobject | nullrequired10 fields
idstringrequirednamestringrequiredstatusstringrequiredtitlestring | nullrequiredteamstring | nullrequiredlocationstring | nullrequiredcountrystring | nullrequiredcontract_typestring | nullrequiredstartstring | nullrequiredlast_daystring | nullrequired
eventsobject[]required11 fields
idstringrequiredkindstring (enum)requiredOne of:
inquiry_started,inquiry_ended,suspension_started,suspension_ended,charges_delivered,defence_extended,defence_received,union_named,evidence_requested,evidence_done,evidence_refused,hearing_offered,hearing_held,expediente_opened,file_to_council,opinion_received,cite_sent,cite_opinion,decision_delivered,sanction_applied,contact_recorded,registered_letter_sent,claim_filed,claim_ended,note,item_removed,converted,closed,reopened.labelstringrequireddatestringrequiredreceived_onstring | nullrequireddue_onstring | nullrequiredrefstring | nullrequirednotestring | nullrequireditem_idsstring[]requiredbyobjectrequired2 fields
user_idstringrequirednamestringrequired
atstringrequired
itemsobject[]required16 fields
idstringrequireddoc_nostringrequiredkind"record" | "file" | "statement"requiredrole"evidence" | "defence" | "statement" | "proof" | "opinion" | "other"requiredlabelstringrequiredonstring | nullrequiredsourceobject | nullrequired4 fields
modulestringrequiredtypestring (enum)requiredOne of:
timeclock_no_record,timeclock_late,timeoff,shifts,training_assigned,training_failed,documents,org_facts,earlier_case.refstringrequiredhashstringrequired
snapshotobject | nullrequiredfileobject | nullrequired6 fields
namestringrequiredcontent_typestringrequiredsizeintegerrequiredsha256string | nullrequiredpagesinteger | nullrequiredstatus"pending" | "ready"required
emailobject | nullrequired8 fields
fromstring | nullrequiredtostring | nullrequiredccstring | nullrequireddatestring | nullrequiredsubjectstring | nullrequiredtextstringrequiredtruncatedbooleanrequiredattachmentsobject[]required5 fields
indexintegerrequirednamestringrequiredcontent_typestringrequiredsizeintegerrequiredextracted_item_idstring | nullrequired
statementstring | nullrequiredconfirmed"unjustified" | "justified"requiredfrom_requestobject | nullrequired2 fields
request_idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
linked_byobjectrequired2 fields
user_idstringrequirednamestringrequired
linked_atstringrequiredremovedobject | nullrequired3 fields
atstringrequiredbystringrequiredreasonstring | nullrequired
requestsobject[]required8 fields
idstringrequiredtoobjectrequired2 fields
idstringrequirednamestringrequired
askstringrequiredduestring | nullrequiredstatus"open" | "answered" | "cancelled" | "expired"requiredanswered_atstring | nullrequireditem_idsstring[]requiredatstringrequired
counterobject | nullrequired5 fields
yearintegerrequiredtotalintegerrequiredlongest_runintegerrequiredreachesbooleanrequiredunconfirmedintegerrequired
allowed_eventsstring (enum)[]requiredOne of:
inquiry_started,inquiry_ended,suspension_started,suspension_ended,charges_delivered,defence_extended,defence_received,union_named,evidence_requested,evidence_done,evidence_refused,hearing_offered,hearing_held,expediente_opened,file_to_council,opinion_received,cite_sent,cite_opinion,decision_delivered,sanction_applied,contact_recorded,registered_letter_sent,claim_filed,claim_ended,note,item_removed,converted,closed,reopened.retention_untilstring | nullrequiredmeobjectrequired3 fields
lettersbooleanrequiredanswerbooleanrequiredconsultbooleanrequired
canobjectrequired2 fields
editbooleanrequiredleadbooleanrequired
filesobjectrequired4 fields
countintegerrequiredbytesintegerrequiredmax_filesintegerrequiredmax_bytesintegerrequired
bundleobjectrequired2 fields
lastobject | nullrequired2 fields
atstringrequiredpagesintegerrequired
left_todayintegerrequired
todaystringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/team.set \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"case_id": "c1",
"team": [
{
"user_id": "u1",
"role": "lead"
},
{
"user_id": "u2",
"role": "decider"
}
]
}'const res = await fetch('https://api.bizisy.com/v1/relations/team.set', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"case_id": "c1",
"team": [
{
"user_id": "u1",
"role": "lead"
},
{
"user_id": "u2",
"role": "decider"
}
]
}),
});
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/relations/team.set",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"case_id": "c1",
"team": [
{
"user_id": "u1",
"role": "lead",
},
{
"user_id": "u2",
"role": "decider",
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "c1",
"number": "ER-2026-0001",
"kind": "dismissal",
"status": "open",
"phase": "defence",
"person": {
"id": "p2",
"name": "Bea Silva"
},
"next": {
"label": "Defence period",
"basis": "CT 355(1)",
"due": "2026-12-07",
"days_left": 14,
"state": "running",
"lapse": false
},
"lapsed": false,
"hold": false,
"team": [
{
"user_id": "u1",
"name": "Rui Lopes",
"role": "lead",
"via_break_glass": false
}
],
"my_role": "lead",
"opened_on": "2026-11-05",
"closed_at": null,
"outcome": null,
"pack": {
"id": "pt",
"version": "2026-11-22",
"name": "Portugal: Código do Trabalho",
"legal": true,
"note": "Deadlines from the Código do Trabalho.",
"current_version": "2026-11-22",
"newer": false
},
"country": "PT",
"facts": [
{
"id": "f1",
"title": "Absent without notice",
"dates": [
"2026-11-03"
],
"learned_on": "2026-11-05",
"crime": false,
"crime_until": null,
"severity": null
}
],
"flags": {
"rep": false,
"union": false,
"candidate": false,
"micro": false,
"council": false,
"parental": false,
"complaint_on": null,
"equality_complaint": false,
"whistleblower": false
},
"parental_from_timeoff": false,
"absent_since": null,
"clocks": [
{
"key": "C6",
"clock": "C6",
"type": "wait",
"fact_id": null,
"label": "Defence period",
"basis": "CT 355(1)",
"url": "https://www.pgdlisboa.pt/leis/lei_mostra_articulado.php?artigo_id=1047A0355&nid=1047&tabela=leis",
"confidence": "verified",
"stops": "The answer received early, or an extension the team grants (recorded)",
"if_missed": "The team may go on with the procedure.",
"lapse": false,
"started_on": "2026-11-20",
"due": "2026-12-07",
"state": "running",
"days_left": 14,
"note": null
}
],
"next3": [
{
"key": "C6",
"clock": "C6",
"type": "wait",
"fact_id": null,
"label": "Defence period",
"basis": "CT 355(1)",
"url": "https://www.pgdlisboa.pt/leis/lei_mostra_articulado.php?artigo_id=1047A0355&nid=1047&tabela=leis",
"confidence": "verified",
"stops": "The answer received early, or an extension the team grants (recorded)",
"if_missed": "The team may go on with the procedure.",
"lapse": false,
"started_on": "2026-11-20",
"due": "2026-12-07",
"state": "running",
"days_left": 14,
"note": null
}
],
"checks": {
"charges": [],
"decision": [
{
"id": "defence_open",
"message": "The defence period isn't over.",
"basis": "CT 355",
"url": "https://www.pgdlisboa.pt/leis/lei_mostra_articulado.php?artigo_id=1047A0355&nid=1047&tabela=leis",
"confidence": "verified",
"level": "red",
"values": {}
}
]
},
"protected": [],
"person_facts": {
"id": "p2",
"name": "Bea Silva",
"status": "active",
"title": "Agent",
"team": "Support",
"location": "Lisboa",
"country": "PT",
"contract_type": "open_ended",
"start": "2024-01-08",
"last_day": null
},
"events": [
{
"id": "e1",
"kind": "charges_delivered",
"label": "Nota de culpa delivered",
"date": "2026-11-18",
"received_on": "2026-11-20",
"due_on": null,
"ref": null,
"note": null,
"item_ids": [],
"by": {
"user_id": "u1",
"name": "Rui Lopes"
},
"at": "2026-11-21T10:00:00.000Z"
}
],
"items": [
{
"id": "i1",
"doc_no": "D-1",
"kind": "record",
"role": "evidence",
"label": "No record, 2026-11-03, scheduled 09:00–18:00",
"on": "2026-11-03",
"source": {
"module": "timeclock",
"type": "timeclock_no_record",
"ref": "no_record:2026-11-03",
"hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
},
"snapshot": {
"date": "2026-11-03",
"start": "09:00",
"end": "18:00"
},
"file": null,
"email": null,
"statement": null,
"confirmed": null,
"from_request": null,
"linked_by": {
"user_id": "u1",
"name": "Rui Lopes"
},
"linked_at": "2026-11-21T10:00:00.000Z",
"removed": null
}
],
"requests": [],
"counter": {
"year": 2026,
"total": 0,
"longest_run": 0,
"reaches": false,
"unconfirmed": 1
},
"allowed_events": [
"charges_delivered",
"defence_received",
"note"
],
"retention_until": null,
"me": {
"letters": true,
"answer": true,
"consult": true
},
"can": {
"edit": true,
"lead": true
},
"files": {
"count": 0,
"bytes": 0,
"max_files": 500,
"max_bytes": 2000000000
},
"bundle": {
"last": null,
"left_today": 10
},
"today": "2026-11-23"
}
}Join a case from the register (break-glass)#
POST/v1/relations/team.joinWrite
For owners and admins: joins a case from the register as a reviewer, to see its content (break-glass). Give the reason. It is recorded on the case's timeline and in Activity, and the case's lead is emailed at once (the case number only). Never your own case. In the app only.
- Web app only
- Refused for API keys and connected apps. Employee relations works only in the Bizisy app: a case is confidential to its team.
- MCP tool
relations_team_joinon 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
case_idstringrequired1–64 characters.
reasonstringrequired3–500 characters.
Returns
36 fields
idstringrequirednumberstringrequiredkind"dismissal" | "sanction" | "abandonment" | "inquiry"requiredstatus"open" | "closed"requiredphasestring (enum)requiredOne of:
facts,inquiry,defence,evidence,opinion,decision,decided,applied,absence,letter_sent,closed.personobject | nullrequired2 fields
idstringrequirednamestringrequired
nextobject | nullrequired6 fields
labelstringrequiredbasisstringrequiredduestringrequireddays_leftintegerrequiredstate"waiting" | "running" | "ended" | "met" | "missed" | "info"requiredlapsebooleanrequired
lapsedbooleanrequiredholdbooleanrequiredteamobject[]required4 fields
user_idstringrequirednamestringrequiredrole"lead" | "member" | "decider" | "reviewer"requiredvia_break_glassbooleanrequired
my_role"lead" | "member" | "decider" | "reviewer"requirednull: a register row (owners and admins, not on the team).
opened_onstringrequiredclosed_atstring | nullrequiredoutcome"no_sanction" | "sanction" | "dismissal" | "dropped" | "resigned" | "abandonment"requiredpackobjectrequired7 fields
id"pt" | "es" | "eu"requiredversionstringrequirednamestringrequiredlegalbooleanrequirednotestringrequiredcurrent_versionstringrequirednewerbooleanrequired
countrystring | nullrequiredfactsobject[]required7 fields
idstringrequiredtitlestringrequireddatesstring[]requiredlearned_onstring | nullrequiredcrimebooleanrequiredcrime_untilstring | nullrequiredseverity"leve" | "grave" | "muy_grave"required
flagsobjectrequired9 fields
repbooleanrequiredunionbooleanrequiredcandidatebooleanrequiredmicrobooleanrequiredcouncilbooleanrequiredparentalbooleanrequiredcomplaint_onstring | nullrequiredequality_complaintbooleanrequiredwhistleblowerbooleanrequired
parental_from_timeoffbooleanrequiredabsent_sincestring | nullrequiredclocksobject[]required16 fields
keystringrequiredclockstringrequiredtype"deadline" | "wait" | "info"requiredfact_idstring | nullrequiredlabelstringrequiredEnglish; the app translates it.
basisstringrequiredThe article, untranslated: "CT 329(2)".
urlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredstopsstringrequiredif_missedstringrequiredlapsebooleanrequiredstarted_onstring | nullrequiredduestring | nullrequiredstate"waiting" | "running" | "ended" | "met" | "missed" | "info"requireddays_leftinteger | nullrequirednotestring | nullrequired
next3object[]required16 fields
keystringrequiredclockstringrequiredtype"deadline" | "wait" | "info"requiredfact_idstring | nullrequiredlabelstringrequiredEnglish; the app translates it.
basisstringrequiredThe article, untranslated: "CT 329(2)".
urlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredstopsstringrequiredif_missedstringrequiredlapsebooleanrequiredstarted_onstring | nullrequiredduestring | nullrequiredstate"waiting" | "running" | "ended" | "met" | "missed" | "info"requireddays_leftinteger | nullrequirednotestring | nullrequired
checksobjectrequired2 fields
chargesobject[]required7 fields
idstringrequiredmessagestringrequiredEnglish with {n}, {date}, {clock} filled from values.
basisstringrequiredurlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredlevel"red" | "warning" | "info"requiredvaluesobjectrequired
decisionobject[]required7 fields
idstringrequiredmessagestringrequiredEnglish with {n}, {date}, {clock} filled from values.
basisstringrequiredurlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredlevel"red" | "warning" | "info"requiredvaluesobjectrequired
protectedobject[]required7 fields
idstringrequiredmessagestringrequiredEnglish with {n}, {date}, {clock} filled from values.
basisstringrequiredurlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredlevel"red" | "warning" | "info"requiredvaluesobjectrequired
person_factsobject | nullrequired10 fields
idstringrequirednamestringrequiredstatusstringrequiredtitlestring | nullrequiredteamstring | nullrequiredlocationstring | nullrequiredcountrystring | nullrequiredcontract_typestring | nullrequiredstartstring | nullrequiredlast_daystring | nullrequired
eventsobject[]required11 fields
idstringrequiredkindstring (enum)requiredOne of:
inquiry_started,inquiry_ended,suspension_started,suspension_ended,charges_delivered,defence_extended,defence_received,union_named,evidence_requested,evidence_done,evidence_refused,hearing_offered,hearing_held,expediente_opened,file_to_council,opinion_received,cite_sent,cite_opinion,decision_delivered,sanction_applied,contact_recorded,registered_letter_sent,claim_filed,claim_ended,note,item_removed,converted,closed,reopened.labelstringrequireddatestringrequiredreceived_onstring | nullrequireddue_onstring | nullrequiredrefstring | nullrequirednotestring | nullrequireditem_idsstring[]requiredbyobjectrequired2 fields
user_idstringrequirednamestringrequired
atstringrequired
itemsobject[]required16 fields
idstringrequireddoc_nostringrequiredkind"record" | "file" | "statement"requiredrole"evidence" | "defence" | "statement" | "proof" | "opinion" | "other"requiredlabelstringrequiredonstring | nullrequiredsourceobject | nullrequired4 fields
modulestringrequiredtypestring (enum)requiredOne of:
timeclock_no_record,timeclock_late,timeoff,shifts,training_assigned,training_failed,documents,org_facts,earlier_case.refstringrequiredhashstringrequired
snapshotobject | nullrequiredfileobject | nullrequired6 fields
namestringrequiredcontent_typestringrequiredsizeintegerrequiredsha256string | nullrequiredpagesinteger | nullrequiredstatus"pending" | "ready"required
emailobject | nullrequired8 fields
fromstring | nullrequiredtostring | nullrequiredccstring | nullrequireddatestring | nullrequiredsubjectstring | nullrequiredtextstringrequiredtruncatedbooleanrequiredattachmentsobject[]required5 fields
indexintegerrequirednamestringrequiredcontent_typestringrequiredsizeintegerrequiredextracted_item_idstring | nullrequired
statementstring | nullrequiredconfirmed"unjustified" | "justified"requiredfrom_requestobject | nullrequired2 fields
request_idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
linked_byobjectrequired2 fields
user_idstringrequirednamestringrequired
linked_atstringrequiredremovedobject | nullrequired3 fields
atstringrequiredbystringrequiredreasonstring | nullrequired
requestsobject[]required8 fields
idstringrequiredtoobjectrequired2 fields
idstringrequirednamestringrequired
askstringrequiredduestring | nullrequiredstatus"open" | "answered" | "cancelled" | "expired"requiredanswered_atstring | nullrequireditem_idsstring[]requiredatstringrequired
counterobject | nullrequired5 fields
yearintegerrequiredtotalintegerrequiredlongest_runintegerrequiredreachesbooleanrequiredunconfirmedintegerrequired
allowed_eventsstring (enum)[]requiredOne of:
inquiry_started,inquiry_ended,suspension_started,suspension_ended,charges_delivered,defence_extended,defence_received,union_named,evidence_requested,evidence_done,evidence_refused,hearing_offered,hearing_held,expediente_opened,file_to_council,opinion_received,cite_sent,cite_opinion,decision_delivered,sanction_applied,contact_recorded,registered_letter_sent,claim_filed,claim_ended,note,item_removed,converted,closed,reopened.retention_untilstring | nullrequiredmeobjectrequired3 fields
lettersbooleanrequiredanswerbooleanrequiredconsultbooleanrequired
canobjectrequired2 fields
editbooleanrequiredleadbooleanrequired
filesobjectrequired4 fields
countintegerrequiredbytesintegerrequiredmax_filesintegerrequiredmax_bytesintegerrequired
bundleobjectrequired2 fields
lastobject | nullrequired2 fields
atstringrequiredpagesintegerrequired
left_todayintegerrequired
todaystringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/team.join \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"case_id":"c1","reason":"Board review"}'const res = await fetch('https://api.bizisy.com/v1/relations/team.join', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"case_id": "c1",
"reason": "Board review"
}),
});
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/relations/team.join",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"case_id": "c1",
"reason": "Board review",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "c1",
"number": "ER-2026-0001",
"kind": "dismissal",
"status": "open",
"phase": "defence",
"person": {
"id": "p2",
"name": "Bea Silva"
},
"next": {
"label": "Defence period",
"basis": "CT 355(1)",
"due": "2026-12-07",
"days_left": 14,
"state": "running",
"lapse": false
},
"lapsed": false,
"hold": false,
"team": [
{
"user_id": "u1",
"name": "Rui Lopes",
"role": "lead",
"via_break_glass": false
}
],
"my_role": "reviewer",
"opened_on": "2026-11-05",
"closed_at": null,
"outcome": null,
"pack": {
"id": "pt",
"version": "2026-11-22",
"name": "Portugal: Código do Trabalho",
"legal": true,
"note": "Deadlines from the Código do Trabalho.",
"current_version": "2026-11-22",
"newer": false
},
"country": "PT",
"facts": [
{
"id": "f1",
"title": "Absent without notice",
"dates": [
"2026-11-03"
],
"learned_on": "2026-11-05",
"crime": false,
"crime_until": null,
"severity": null
}
],
"flags": {
"rep": false,
"union": false,
"candidate": false,
"micro": false,
"council": false,
"parental": false,
"complaint_on": null,
"equality_complaint": false,
"whistleblower": false
},
"parental_from_timeoff": false,
"absent_since": null,
"clocks": [
{
"key": "C6",
"clock": "C6",
"type": "wait",
"fact_id": null,
"label": "Defence period",
"basis": "CT 355(1)",
"url": "https://www.pgdlisboa.pt/leis/lei_mostra_articulado.php?artigo_id=1047A0355&nid=1047&tabela=leis",
"confidence": "verified",
"stops": "The answer received early, or an extension the team grants (recorded)",
"if_missed": "The team may go on with the procedure.",
"lapse": false,
"started_on": "2026-11-20",
"due": "2026-12-07",
"state": "running",
"days_left": 14,
"note": null
}
],
"next3": [
{
"key": "C6",
"clock": "C6",
"type": "wait",
"fact_id": null,
"label": "Defence period",
"basis": "CT 355(1)",
"url": "https://www.pgdlisboa.pt/leis/lei_mostra_articulado.php?artigo_id=1047A0355&nid=1047&tabela=leis",
"confidence": "verified",
"stops": "The answer received early, or an extension the team grants (recorded)",
"if_missed": "The team may go on with the procedure.",
"lapse": false,
"started_on": "2026-11-20",
"due": "2026-12-07",
"state": "running",
"days_left": 14,
"note": null
}
],
"checks": {
"charges": [],
"decision": [
{
"id": "defence_open",
"message": "The defence period isn't over.",
"basis": "CT 355",
"url": "https://www.pgdlisboa.pt/leis/lei_mostra_articulado.php?artigo_id=1047A0355&nid=1047&tabela=leis",
"confidence": "verified",
"level": "red",
"values": {}
}
]
},
"protected": [],
"person_facts": {
"id": "p2",
"name": "Bea Silva",
"status": "active",
"title": "Agent",
"team": "Support",
"location": "Lisboa",
"country": "PT",
"contract_type": "open_ended",
"start": "2024-01-08",
"last_day": null
},
"events": [
{
"id": "e1",
"kind": "charges_delivered",
"label": "Nota de culpa delivered",
"date": "2026-11-18",
"received_on": "2026-11-20",
"due_on": null,
"ref": null,
"note": null,
"item_ids": [],
"by": {
"user_id": "u1",
"name": "Rui Lopes"
},
"at": "2026-11-21T10:00:00.000Z"
}
],
"items": [
{
"id": "i1",
"doc_no": "D-1",
"kind": "record",
"role": "evidence",
"label": "No record, 2026-11-03, scheduled 09:00–18:00",
"on": "2026-11-03",
"source": {
"module": "timeclock",
"type": "timeclock_no_record",
"ref": "no_record:2026-11-03",
"hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
},
"snapshot": {
"date": "2026-11-03",
"start": "09:00",
"end": "18:00"
},
"file": null,
"email": null,
"statement": null,
"confirmed": null,
"from_request": null,
"linked_by": {
"user_id": "u1",
"name": "Rui Lopes"
},
"linked_at": "2026-11-21T10:00:00.000Z",
"removed": null
}
],
"requests": [],
"counter": {
"year": 2026,
"total": 0,
"longest_run": 0,
"reaches": false,
"unconfirmed": 1
},
"allowed_events": [
"charges_delivered",
"defence_received",
"note"
],
"retention_until": null,
"me": {
"letters": true,
"answer": true,
"consult": true
},
"can": {
"edit": true,
"lead": true
},
"files": {
"count": 0,
"bytes": 0,
"max_files": 500,
"max_bytes": 2000000000
},
"bundle": {
"last": null,
"left_today": 10
},
"today": "2026-11-23"
}
}Record a case event#
POST/v1/relations/events.recordWrite
Records what happened in a case, on the day it happened: the written charges (nota de culpa) delivered and the day the person received them, the answer received, an extension of the defence period (due_on), evidence steps requested and done or refused with reasons (ref: the request event), the file sent to the works council, opinions, CITE, hearings, the decision delivered, the sanction applied, contact from an absent person, the registered letter, a claim filed (the case is then on legal hold) or ended, a note. Bizisy recomputes every deadline from the events. A dry run shows the procedure check for that step (warnings with the article, never a block) and the deadlines after it. The lead and members. In the app only.
- Web app only
- Refused for API keys and connected apps. Employee relations works only in the Bizisy app: a case is confidential to its team.
- MCP tool
relations_events_recordon 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
case_idstringrequired1–64 characters.
kindstring (enum)requiredOne of:
inquiry_started,inquiry_ended,suspension_started,suspension_ended,charges_delivered,defence_extended,defence_received,union_named,evidence_requested,evidence_done,evidence_refused,hearing_offered,hearing_held,expediente_opened,file_to_council,opinion_received,cite_sent,cite_opinion,decision_delivered,sanction_applied,contact_recorded,registered_letter_sent,claim_filed,claim_ended,note,item_removed,converted,closed,reopened.datestringrequiredThe day it happened (sent, held, started).
Pattern
^\d{4}-\d{2}-\d{2}$.received_onstring | nullThe day the person (or the council) received it: delivery events start their clocks from it.
Pattern
^\d{4}-\d{2}-\d{2}$. Defaultnull.due_onstring | nulldefence_extended: the new last day.
Pattern
^\d{4}-\d{2}-\d{2}$. Defaultnull.refstring | nullevidence_done / evidence_refused: the evidence_requested event id. cite_opinion: favourable or unfavourable.
Up to 64 characters. Default
null.notestring | nullThe team's note (who, what, reasons for a refusal).
Up to 4000 characters. Default
null.item_idsstring[]Items of the case file attached as proof (a signed receipt, the AR card).
1–64 characters. Up to 25 items.
Returns
eventobjectrequired3 fields
idstring | nullrequiredkindstring (enum)requiredOne of:
inquiry_started,inquiry_ended,suspension_started,suspension_ended,charges_delivered,defence_extended,defence_received,union_named,evidence_requested,evidence_done,evidence_refused,hearing_offered,hearing_held,expediente_opened,file_to_council,opinion_received,cite_sent,cite_opinion,decision_delivered,sanction_applied,contact_recorded,registered_letter_sent,claim_filed,claim_ended,note,item_removed,converted,closed,reopened.datestringrequired
checksobject[]requiredThe procedure check for this step, before it.
7 fields
idstringrequiredmessagestringrequiredEnglish with {n}, {date}, {clock} filled from values.
basisstringrequiredurlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredlevel"red" | "warning" | "info"requiredvaluesobjectrequired
clocksobject[]requiredThe deadlines after it.
16 fields
keystringrequiredclockstringrequiredtype"deadline" | "wait" | "info"requiredfact_idstring | nullrequiredlabelstringrequiredEnglish; the app translates it.
basisstringrequiredThe article, untranslated: "CT 329(2)".
urlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredstopsstringrequiredif_missedstringrequiredlapsebooleanrequiredstarted_onstring | nullrequiredduestring | nullrequiredstate"waiting" | "running" | "ended" | "met" | "missed" | "info"requireddays_leftinteger | nullrequirednotestring | nullrequired
caseobject | nullrequiredThe case after it (null on a dry run).
36 fields
idstringrequirednumberstringrequiredkind"dismissal" | "sanction" | "abandonment" | "inquiry"requiredstatus"open" | "closed"requiredphasestring (enum)requiredOne of:
facts,inquiry,defence,evidence,opinion,decision,decided,applied,absence,letter_sent,closed.personobject | nullrequired2 fields
idstringrequirednamestringrequired
nextobject | nullrequired6 fields
labelstringrequiredbasisstringrequiredduestringrequireddays_leftintegerrequiredstate"waiting" | "running" | "ended" | "met" | "missed" | "info"requiredlapsebooleanrequired
lapsedbooleanrequiredholdbooleanrequiredteamobject[]required4 fields
user_idstringrequirednamestringrequiredrole"lead" | "member" | "decider" | "reviewer"requiredvia_break_glassbooleanrequired
my_role"lead" | "member" | "decider" | "reviewer"requirednull: a register row (owners and admins, not on the team).
opened_onstringrequiredclosed_atstring | nullrequiredoutcome"no_sanction" | "sanction" | "dismissal" | "dropped" | "resigned" | "abandonment"requiredpackobjectrequired7 fields
id"pt" | "es" | "eu"requiredversionstringrequirednamestringrequiredlegalbooleanrequirednotestringrequiredcurrent_versionstringrequirednewerbooleanrequired
countrystring | nullrequiredfactsobject[]required7 fields
idstringrequiredtitlestringrequireddatesstring[]requiredlearned_onstring | nullrequiredcrimebooleanrequiredcrime_untilstring | nullrequiredseverity"leve" | "grave" | "muy_grave"required
flagsobjectrequired9 fields
repbooleanrequiredunionbooleanrequiredcandidatebooleanrequiredmicrobooleanrequiredcouncilbooleanrequiredparentalbooleanrequiredcomplaint_onstring | nullrequiredequality_complaintbooleanrequiredwhistleblowerbooleanrequired
parental_from_timeoffbooleanrequiredabsent_sincestring | nullrequiredclocksobject[]required16 fields
keystringrequiredclockstringrequiredtype"deadline" | "wait" | "info"requiredfact_idstring | nullrequiredlabelstringrequiredEnglish; the app translates it.
basisstringrequiredThe article, untranslated: "CT 329(2)".
urlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredstopsstringrequiredif_missedstringrequiredlapsebooleanrequiredstarted_onstring | nullrequiredduestring | nullrequiredstate"waiting" | "running" | "ended" | "met" | "missed" | "info"requireddays_leftinteger | nullrequirednotestring | nullrequired
next3object[]required16 fields
keystringrequiredclockstringrequiredtype"deadline" | "wait" | "info"requiredfact_idstring | nullrequiredlabelstringrequiredEnglish; the app translates it.
basisstringrequiredThe article, untranslated: "CT 329(2)".
urlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredstopsstringrequiredif_missedstringrequiredlapsebooleanrequiredstarted_onstring | nullrequiredduestring | nullrequiredstate"waiting" | "running" | "ended" | "met" | "missed" | "info"requireddays_leftinteger | nullrequirednotestring | nullrequired
checksobjectrequired2 fields
chargesobject[]required7 fields
idstringrequiredmessagestringrequiredEnglish with {n}, {date}, {clock} filled from values.
basisstringrequiredurlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredlevel"red" | "warning" | "info"requiredvaluesobjectrequired
decisionobject[]required7 fields
idstringrequiredmessagestringrequiredEnglish with {n}, {date}, {clock} filled from values.
basisstringrequiredurlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredlevel"red" | "warning" | "info"requiredvaluesobjectrequired
protectedobject[]required7 fields
idstringrequiredmessagestringrequiredEnglish with {n}, {date}, {clock} filled from values.
basisstringrequiredurlstringrequiredconfidence"verified" | "medium" | "uncertain"requiredlevel"red" | "warning" | "info"requiredvaluesobjectrequired
person_factsobject | nullrequired10 fields
idstringrequirednamestringrequiredstatusstringrequiredtitlestring | nullrequiredteamstring | nullrequiredlocationstring | nullrequiredcountrystring | nullrequiredcontract_typestring | nullrequiredstartstring | nullrequiredlast_daystring | nullrequired
eventsobject[]required11 fields
idstringrequiredkindstring (enum)requiredOne of:
inquiry_started,inquiry_ended,suspension_started,suspension_ended,charges_delivered,defence_extended,defence_received,union_named,evidence_requested,evidence_done,evidence_refused,hearing_offered,hearing_held,expediente_opened,file_to_council,opinion_received,cite_sent,cite_opinion,decision_delivered,sanction_applied,contact_recorded,registered_letter_sent,claim_filed,claim_ended,note,item_removed,converted,closed,reopened.labelstringrequireddatestringrequiredreceived_onstring | nullrequireddue_onstring | nullrequiredrefstring | nullrequirednotestring | nullrequireditem_idsstring[]requiredbyobjectrequired2 fields
user_idstringrequirednamestringrequired
atstringrequired
itemsobject[]required16 fields
idstringrequireddoc_nostringrequiredkind"record" | "file" | "statement"requiredrole"evidence" | "defence" | "statement" | "proof" | "opinion" | "other"requiredlabelstringrequiredonstring | nullrequiredsourceobject | nullrequired4 fields
modulestringrequiredtypestring (enum)requiredOne of:
timeclock_no_record,timeclock_late,timeoff,shifts,training_assigned,training_failed,documents,org_facts,earlier_case.refstringrequiredhashstringrequired
snapshotobject | nullrequiredfileobject | nullrequired6 fields
namestringrequiredcontent_typestringrequiredsizeintegerrequiredsha256string | nullrequiredpagesinteger | nullrequiredstatus"pending" | "ready"required
emailobject | nullrequired8 fields
fromstring | nullrequiredtostring | nullrequiredccstring | nullrequireddatestring | nullrequiredsubjectstring | nullrequiredtextstringrequiredtruncatedbooleanrequiredattachmentsobject[]required5 fields
indexintegerrequirednamestringrequiredcontent_typestringrequiredsizeintegerrequiredextracted_item_idstring | nullrequired
statementstring | nullrequiredconfirmed"unjustified" | "justified"requiredfrom_requestobject | nullrequired2 fields
request_idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
linked_byobjectrequired2 fields
user_idstringrequirednamestringrequired
linked_atstringrequiredremovedobject | nullrequired3 fields
atstringrequiredbystringrequiredreasonstring | nullrequired
requestsobject[]required8 fields
idstringrequiredtoobjectrequired2 fields
idstringrequirednamestringrequired
askstringrequiredduestring | nullrequiredstatus"open" | "answered" | "cancelled" | "expired"requiredanswered_atstring | nullrequireditem_idsstring[]requiredatstringrequired
counterobject | nullrequired5 fields
yearintegerrequiredtotalintegerrequiredlongest_runintegerrequiredreachesbooleanrequiredunconfirmedintegerrequired
allowed_eventsstring (enum)[]requiredOne of:
inquiry_started,inquiry_ended,suspension_started,suspension_ended,charges_delivered,defence_extended,defence_received,union_named,evidence_requested,evidence_done,evidence_refused,hearing_offered,hearing_held,expediente_opened,file_to_council,opinion_received,cite_sent,cite_opinion,decision_delivered,sanction_applied,contact_recorded,registered_letter_sent,claim_filed,claim_ended,note,item_removed,converted,closed,reopened.retention_untilstring | nullrequiredmeobjectrequired3 fields
lettersbooleanrequiredanswerbooleanrequiredconsultbooleanrequired
canobjectrequired2 fields
editbooleanrequiredleadbooleanrequired
filesobjectrequired4 fields
countintegerrequiredbytesintegerrequiredmax_filesintegerrequiredmax_bytesintegerrequired
bundleobjectrequired2 fields
lastobject | nullrequired2 fields
atstringrequiredpagesintegerrequired
left_todayintegerrequired
todaystringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/events.record \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"case_id": "c1",
"kind": "charges_delivered",
"date": "2026-11-18",
"received_on": "2026-11-20"
}'const res = await fetch('https://api.bizisy.com/v1/relations/events.record', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"case_id": "c1",
"kind": "charges_delivered",
"date": "2026-11-18",
"received_on": "2026-11-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/relations/events.record",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"case_id": "c1",
"kind": "charges_delivered",
"date": "2026-11-18",
"received_on": "2026-11-20",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"event": {
"id": "e1",
"kind": "charges_delivered",
"date": "2026-11-18"
},
"checks": [],
"clocks": [
{
"key": "C6",
"clock": "C6",
"type": "wait",
"fact_id": null,
"label": "Defence period",
"basis": "CT 355(1)",
"url": "https://www.pgdlisboa.pt/leis/lei_mostra_articulado.php?artigo_id=1047A0355&nid=1047&tabela=leis",
"confidence": "verified",
"stops": "The answer received early, or an extension the team grants (recorded)",
"if_missed": "The team may go on with the procedure.",
"lapse": false,
"started_on": "2026-11-20",
"due": "2026-12-07",
"state": "running",
"days_left": 14,
"note": null
}
],
"case": {
"id": "c1",
"number": "ER-2026-0001",
"kind": "dismissal",
"status": "open",
"phase": "defence",
"person": {
"id": "p2",
"name": "Bea Silva"
},
"next": {
"label": "Defence period",
"basis": "CT 355(1)",
"due": "2026-12-07",
"days_left": 14,
"state": "running",
"lapse": false
},
"lapsed": false,
"hold": false,
"team": [
{
"user_id": "u1",
"name": "Rui Lopes",
"role": "lead",
"via_break_glass": false
}
],
"my_role": "lead",
"opened_on": "2026-11-05",
"closed_at": null,
"outcome": null,
"pack": {
"id": "pt",
"version": "2026-11-22",
"name": "Portugal: Código do Trabalho",
"legal": true,
"note": "Deadlines from the Código do Trabalho.",
"current_version": "2026-11-22",
"newer": false
},
"country": "PT",
"facts": [
{
"id": "f1",
"title": "Absent without notice",
"dates": [
"2026-11-03"
],
"learned_on": "2026-11-05",
"crime": false,
"crime_until": null,
"severity": null
}
],
"flags": {
"rep": false,
"union": false,
"candidate": false,
"micro": false,
"council": false,
"parental": false,
"complaint_on": null,
"equality_complaint": false,
"whistleblower": false
},
"parental_from_timeoff": false,
"absent_since": null,
"clocks": [
{
"key": "C6",
"clock": "C6",
"type": "wait",
"fact_id": null,
"label": "Defence period",
"basis": "CT 355(1)",
"url": "https://www.pgdlisboa.pt/leis/lei_mostra_articulado.php?artigo_id=1047A0355&nid=1047&tabela=leis",
"confidence": "verified",
"stops": "The answer received early, or an extension the team grants (recorded)",
"if_missed": "The team may go on with the procedure.",
"lapse": false,
"started_on": "2026-11-20",
"due": "2026-12-07",
"state": "running",
"days_left": 14,
"note": null
}
],
"next3": [
{
"key": "C6",
"clock": "C6",
"type": "wait",
"fact_id": null,
"label": "Defence period",
"basis": "CT 355(1)",
"url": "https://www.pgdlisboa.pt/leis/lei_mostra_articulado.php?artigo_id=1047A0355&nid=1047&tabela=leis",
"confidence": "verified",
"stops": "The answer received early, or an extension the team grants (recorded)",
"if_missed": "The team may go on with the procedure.",
"lapse": false,
"started_on": "2026-11-20",
"due": "2026-12-07",
"state": "running",
"days_left": 14,
"note": null
}
],
"checks": {
"charges": [],
"decision": [
{
"id": "defence_open",
"message": "The defence period isn't over.",
"basis": "CT 355",
"url": "https://www.pgdlisboa.pt/leis/lei_mostra_articulado.php?artigo_id=1047A0355&nid=1047&tabela=leis",
"confidence": "verified",
"level": "red",
"values": {}
}
]
},
"protected": [],
"person_facts": {
"id": "p2",
"name": "Bea Silva",
"status": "active",
"title": "Agent",
"team": "Support",
"location": "Lisboa",
"country": "PT",
"contract_type": "open_ended",
"start": "2024-01-08",
"last_day": null
},
"events": [
{
"id": "e1",
"kind": "charges_delivered",
"label": "Nota de culpa delivered",
"date": "2026-11-18",
"received_on": "2026-11-20",
"due_on": null,
"ref": null,
"note": null,
"item_ids": [],
"by": {
"user_id": "u1",
"name": "Rui Lopes"
},
"at": "2026-11-21T10:00:00.000Z"
}
],
"items": [
{
"id": "i1",
"doc_no": "D-1",
"kind": "record",
"role": "evidence",
"label": "No record, 2026-11-03, scheduled 09:00–18:00",
"on": "2026-11-03",
"source": {
"module": "timeclock",
"type": "timeclock_no_record",
"ref": "no_record:2026-11-03",
"hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
},
"snapshot": {
"date": "2026-11-03",
"start": "09:00",
"end": "18:00"
},
"file": null,
"email": null,
"statement": null,
"confirmed": null,
"from_request": null,
"linked_by": {
"user_id": "u1",
"name": "Rui Lopes"
},
"linked_at": "2026-11-21T10:00:00.000Z",
"removed": null
}
],
"requests": [],
"counter": {
"year": 2026,
"total": 0,
"longest_run": 0,
"reaches": false,
"unconfirmed": 1
},
"allowed_events": [
"charges_delivered",
"defence_received",
"note"
],
"retention_until": null,
"me": {
"letters": true,
"answer": true,
"consult": true
},
"can": {
"edit": true,
"lead": true
},
"files": {
"count": 0,
"bytes": 0,
"max_files": 500,
"max_bytes": 2000000000
},
"bundle": {
"last": null,
"left_today": 10
},
"today": "2026-11-23"
}
}
}Records to pick as evidence#
POST/v1/relations/evidence.sourcesRead
What one source holds about the case's person between from and to (default the last 60 days; the time clock and shifts read at most 93 days, time off a year): time clock days with no record or late, time off, rostered shifts, mandatory training overdue or failed, their documents, job and contract facts, or earlier closed cases (number, kind, outcome only). Each with the facts as they are now and whether it is already in the file. The lead and members. In the app only.
- Web app only
- Refused for API keys and connected apps. Employee relations works only in the Bizisy app: a case is confidential to its team.
- MCP tool
relations_evidence_sourceson HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
case_idstringrequired1–64 characters.
sourcestring (enum)requiredOne of:
timeclock,timeoff,shifts,training,documents,org,cases.fromstringPattern
^\d{4}-\d{2}-\d{2}$.tostringPattern
^\d{4}-\d{2}-\d{2}$.
Returns
sourcestring (enum)requiredOne of:
timeclock,timeoff,shifts,training,documents,org,cases.availablebooleanrequiredfalse: that module is switched off or not on this server.
fromstringrequiredtostringrequiredmax_daysinteger | nullrequiredcandidatesobject[]required7 fields
typestring (enum)requiredOne of:
timeclock_no_record,timeclock_late,timeoff,shifts,training_assigned,training_failed,documents,org_facts,earlier_case.refstringrequiredlabelstringrequiredonstring | nullrequiredsnapshotobjectrequiredhashstringrequiredlinked_item_idstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/evidence.sources \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"case_id": "c1",
"source": "timeoff",
"from": "2026-01-01",
"to": "2026-11-23"
}'const res = await fetch('https://api.bizisy.com/v1/relations/evidence.sources', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"case_id": "c1",
"source": "timeoff",
"from": "2026-01-01",
"to": "2026-11-23"
}),
});
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/relations/evidence.sources",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"case_id": "c1",
"source": "timeoff",
"from": "2026-01-01",
"to": "2026-11-23",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"source": "timeoff",
"available": true,
"from": "2026-01-01",
"to": "2026-11-23",
"max_days": 93,
"candidates": [
{
"type": "timeclock_no_record",
"ref": "no_record:2026-11-03",
"label": "No record, 2026-11-03, scheduled 09:00–18:00",
"on": "2026-11-03",
"snapshot": {
"date": "2026-11-03"
},
"hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"linked_item_id": null
}
]
}
}Add records to a case file#
POST/v1/relations/items.linkWrite
Adds picked records (source and ref from relations_evidence_sources, at most 50 at a time) to the case file. Bizisy reads each again from its module and keeps a snapshot with provenance (module, record, who, when, a hash); a document from Documents is copied into the case. Time clock days with no record start Unconfirmed: mark them with relations_items_confirm. The lead and members. A dry run shows what would be added. In the app only.
- Web app only
- Refused for API keys and connected apps. Employee relations works only in the Bizisy app: a case is confidential to its team.
- MCP tool
relations_items_linkon 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
case_idstringrequired1–64 characters.
fromstringPattern
^\d{4}-\d{2}-\d{2}$.tostringPattern
^\d{4}-\d{2}-\d{2}$.role"evidence" | "defence" | "statement" | "proof" | "opinion" | "other"Default
"evidence".picksobject[]required1–50 items.
2 fields
sourcestring (enum)requiredOne of:
timeclock,timeoff,shifts,training,documents,org,cases.refstringrequired1–200 characters.
Returns
itemsobject[]required16 fields
idstringrequireddoc_nostringrequiredkind"record" | "file" | "statement"requiredrole"evidence" | "defence" | "statement" | "proof" | "opinion" | "other"requiredlabelstringrequiredonstring | nullrequiredsourceobject | nullrequired4 fields
modulestringrequiredtypestring (enum)requiredOne of:
timeclock_no_record,timeclock_late,timeoff,shifts,training_assigned,training_failed,documents,org_facts,earlier_case.refstringrequiredhashstringrequired
snapshotobject | nullrequiredfileobject | nullrequired6 fields
namestringrequiredcontent_typestringrequiredsizeintegerrequiredsha256string | nullrequiredpagesinteger | nullrequiredstatus"pending" | "ready"required
emailobject | nullrequired8 fields
fromstring | nullrequiredtostring | nullrequiredccstring | nullrequireddatestring | nullrequiredsubjectstring | nullrequiredtextstringrequiredtruncatedbooleanrequiredattachmentsobject[]required5 fields
indexintegerrequirednamestringrequiredcontent_typestringrequiredsizeintegerrequiredextracted_item_idstring | nullrequired
statementstring | nullrequiredconfirmed"unjustified" | "justified"requiredfrom_requestobject | nullrequired2 fields
request_idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
linked_byobjectrequired2 fields
user_idstringrequirednamestringrequired
linked_atstringrequiredremovedobject | nullrequired3 fields
atstringrequiredbystringrequiredreasonstring | nullrequired
skippedstring[]requiredRefs no longer found or already in the file.
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/items.link \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"case_id": "c1",
"picks": [
{
"source": "timeclock",
"ref": "no_record:2026-11-03"
}
]
}'const res = await fetch('https://api.bizisy.com/v1/relations/items.link', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"case_id": "c1",
"picks": [
{
"source": "timeclock",
"ref": "no_record:2026-11-03"
}
]
}),
});
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/relations/items.link",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"case_id": "c1",
"picks": [
{
"source": "timeclock",
"ref": "no_record:2026-11-03",
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"items": [
{
"id": "i1",
"doc_no": "D-1",
"kind": "record",
"role": "evidence",
"label": "No record, 2026-11-03, scheduled 09:00–18:00",
"on": "2026-11-03",
"source": {
"module": "timeclock",
"type": "timeclock_no_record",
"ref": "no_record:2026-11-03",
"hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
},
"snapshot": {
"date": "2026-11-03",
"start": "09:00",
"end": "18:00"
},
"file": null,
"email": null,
"statement": null,
"confirmed": null,
"from_request": null,
"linked_by": {
"user_id": "u1",
"name": "Rui Lopes"
},
"linked_at": "2026-11-21T10:00:00.000Z",
"removed": null
}
],
"skipped": []
}
}Check whether linked records changed#
POST/v1/relations/items.check_sourcesRead
For the case file's linked records, whether the source changed since it was linked (a late justification turned an absence into sick leave, for example): each changed item with the facts now (null: gone). Both versions stay; nothing is changed. The team. In the app only.
- Web app only
- Refused for API keys and connected apps. Employee relations works only in the Bizisy app: a case is confidential to its team.
- MCP tool
relations_items_check_sourceson HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
case_idstringrequired1–64 characters.
Returns
changedobject[]required2 fields
item_idstringrequirednowobject | nullrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/items.check_sources \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"case_id":"c1"}'const res = await fetch('https://api.bizisy.com/v1/relations/items.check_sources', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"case_id": "c1"
}),
});
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/relations/items.check_sources",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"case_id": "c1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"changed": []
}
}Start uploading files to a case file#
POST/v1/relations/items.upload_urlWrite
Starts uploads to the case file (at most 25 files at a time, 5 unfinished per person at once): PDF, Word (DOCX), ODT, text, images (PNG, JPEG, WebP, HEIC) or emails saved as .eml, up to 50 MB and 300 pages each; 500 files and 2 GB a case, counted in the company's storage. Returns signed upload URLs (bound to each file's size and type); then upload the bytes and call relations_items_finish. Outlook .msg files are refused: save the email as PDF or .eml. The lead and members. In the app only.
- Web app only
- Refused for API keys and connected apps. Employee relations works only in the Bizisy app: a case is confidential to its team.
- MCP tool
relations_items_upload_urlon 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
case_idstringrequired1–64 characters.
role"evidence" | "defence" | "statement" | "proof" | "opinion" | "other"Default
"evidence".filesobject[]required1–25 items.
4 fields
namestringrequired1–255 characters.
sizeintegerrequiredFrom 1 to 50000000.
content_typestringrequired1–120 characters.
sha256stringrequiredPattern
^[0-9a-f]{64}$.
Returns
uploadsobject[]required4 fields
item_idstringrequirednamestringrequireduploadobject | nullrequired3 fields
urlstringrequiredmethodstringrequiredheadersobjectrequired
expires_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/items.upload_url \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"case_id": "c1",
"files": [
{
"name": "defence.pdf",
"size": 1000,
"content_type": "application/pdf",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
]
}'const res = await fetch('https://api.bizisy.com/v1/relations/items.upload_url', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"case_id": "c1",
"files": [
{
"name": "defence.pdf",
"size": 1000,
"content_type": "application/pdf",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
]
}),
});
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/relations/items.upload_url",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"case_id": "c1",
"files": [
{
"name": "defence.pdf",
"size": 1000,
"content_type": "application/pdf",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"uploads": [
{
"item_id": "i2",
"name": "defence.pdf",
"upload": {
"url": "https://storage.example/upload",
"method": "PUT",
"headers": {
"content-type": "application/pdf"
}
},
"expires_at": "2026-11-23T10:15:00.000Z"
}
]
}
}Finish uploads to a case file#
POST/v1/relations/items.finishWrite
Checks each uploaded file by its content (type, size, SHA-256; PDFs at most 300 pages), gives it its case document number (D-n) and, for an .eml, reads its headers, text and attachments (never its remote content). The lead and members. In the app only.
- Web app only
- Refused for API keys and connected apps. Employee relations works only in the Bizisy app: a case is confidential to its team.
- MCP tool
relations_items_finishon 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
case_idstringrequired1–64 characters.
item_idsstring[]required1–64 characters. 1–25 items.
Returns
itemsobject[]required16 fields
idstringrequireddoc_nostringrequiredkind"record" | "file" | "statement"requiredrole"evidence" | "defence" | "statement" | "proof" | "opinion" | "other"requiredlabelstringrequiredonstring | nullrequiredsourceobject | nullrequired4 fields
modulestringrequiredtypestring (enum)requiredOne of:
timeclock_no_record,timeclock_late,timeoff,shifts,training_assigned,training_failed,documents,org_facts,earlier_case.refstringrequiredhashstringrequired
snapshotobject | nullrequiredfileobject | nullrequired6 fields
namestringrequiredcontent_typestringrequiredsizeintegerrequiredsha256string | nullrequiredpagesinteger | nullrequiredstatus"pending" | "ready"required
emailobject | nullrequired8 fields
fromstring | nullrequiredtostring | nullrequiredccstring | nullrequireddatestring | nullrequiredsubjectstring | nullrequiredtextstringrequiredtruncatedbooleanrequiredattachmentsobject[]required5 fields
indexintegerrequirednamestringrequiredcontent_typestringrequiredsizeintegerrequiredextracted_item_idstring | nullrequired
statementstring | nullrequiredconfirmed"unjustified" | "justified"requiredfrom_requestobject | nullrequired2 fields
request_idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
linked_byobjectrequired2 fields
user_idstringrequirednamestringrequired
linked_atstringrequiredremovedobject | nullrequired3 fields
atstringrequiredbystringrequiredreasonstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/items.finish \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"case_id":"c1","item_ids":["i2"]}'const res = await fetch('https://api.bizisy.com/v1/relations/items.finish', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"case_id": "c1",
"item_ids": [
"i2"
]
}),
});
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/relations/items.finish",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"case_id": "c1",
"item_ids": [
"i2",
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"items": [
{
"id": "i2",
"doc_no": "D-2",
"kind": "file",
"role": "evidence",
"label": "defence.pdf",
"on": "2026-11-03",
"source": null,
"snapshot": null,
"file": {
"name": "defence.pdf",
"content_type": "application/pdf",
"size": 1000,
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"pages": 3,
"status": "ready"
},
"email": null,
"statement": null,
"confirmed": null,
"from_request": null,
"linked_by": {
"user_id": "u1",
"name": "Rui Lopes"
},
"linked_at": "2026-11-21T10:00:00.000Z",
"removed": null
}
]
}
}Mark days with no record as unjustified or justified#
POST/v1/relations/items.confirmWrite
Marks time clock days with no record in the case file as unjustified or justified (null: back to Unconfirmed). Bizisy can't know whether an absence was justified (CT 253–254 allow a late justification): only confirmed days count toward CT 351(2)(g). The lead and members. In the app only.
- Web app only
- Refused for API keys and connected apps. Employee relations works only in the Bizisy app: a case is confidential to its team.
- MCP tool
relations_items_confirmon 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
case_idstringrequired1–64 characters.
item_idsstring[]required1–64 characters. 1–200 items.
confirmed"unjustified" | "justified"required
Returns
updatedintegerrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/items.confirm \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"case_id":"c1","item_ids":["i1"],"confirmed":"unjustified"}'const res = await fetch('https://api.bizisy.com/v1/relations/items.confirm', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"case_id": "c1",
"item_ids": [
"i1"
],
"confirmed": "unjustified"
}),
});
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/relations/items.confirm",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"case_id": "c1",
"item_ids": [
"i1",
],
"confirmed": "unjustified",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"updated": 1
}
}Remove an item from a case file#
POST/v1/relations/items.removeWrite
Removes an item from the case file: its file is deleted, and the removal stays on the timeline with who, when and why (never silent); its D-number is not reused. The lead and members. In the app only.
- Web app only
- Refused for API keys and connected apps. Employee relations works only in the Bizisy app: a case is confidential to its team.
- MCP tool
relations_items_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
case_idstringrequired1–64 characters.
item_idstringrequired1–64 characters.
reasonstring | nullUp to 500 characters. Default
null.
Returns
16 fields
idstringrequireddoc_nostringrequiredkind"record" | "file" | "statement"requiredrole"evidence" | "defence" | "statement" | "proof" | "opinion" | "other"requiredlabelstringrequiredonstring | nullrequiredsourceobject | nullrequired4 fields
modulestringrequiredtypestring (enum)requiredOne of:
timeclock_no_record,timeclock_late,timeoff,shifts,training_assigned,training_failed,documents,org_facts,earlier_case.refstringrequiredhashstringrequired
snapshotobject | nullrequiredfileobject | nullrequired6 fields
namestringrequiredcontent_typestringrequiredsizeintegerrequiredsha256string | nullrequiredpagesinteger | nullrequiredstatus"pending" | "ready"required
emailobject | nullrequired8 fields
fromstring | nullrequiredtostring | nullrequiredccstring | nullrequireddatestring | nullrequiredsubjectstring | nullrequiredtextstringrequiredtruncatedbooleanrequiredattachmentsobject[]required5 fields
indexintegerrequirednamestringrequiredcontent_typestringrequiredsizeintegerrequiredextracted_item_idstring | nullrequired
statementstring | nullrequiredconfirmed"unjustified" | "justified"requiredfrom_requestobject | nullrequired2 fields
request_idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
linked_byobjectrequired2 fields
user_idstringrequirednamestringrequired
linked_atstringrequiredremovedobject | nullrequired3 fields
atstringrequiredbystringrequiredreasonstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/items.remove \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"case_id":"c1","item_id":"i1","reason":"Justified late"}'const res = await fetch('https://api.bizisy.com/v1/relations/items.remove', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"case_id": "c1",
"item_id": "i1",
"reason": "Justified late"
}),
});
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/relations/items.remove",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"case_id": "c1",
"item_id": "i1",
"reason": "Justified late",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "i1",
"doc_no": "D-1",
"kind": "record",
"role": "evidence",
"label": "No record, 2026-11-03, scheduled 09:00–18:00",
"on": "2026-11-03",
"source": {
"module": "timeclock",
"type": "timeclock_no_record",
"ref": "no_record:2026-11-03",
"hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
},
"snapshot": {
"date": "2026-11-03",
"start": "09:00",
"end": "18:00"
},
"file": null,
"email": null,
"statement": null,
"confirmed": null,
"from_request": null,
"linked_by": {
"user_id": "u1",
"name": "Rui Lopes"
},
"linked_at": "2026-11-21T10:00:00.000Z",
"removed": {
"at": "2026-11-23T10:00:00.000Z",
"by": "Rui Lopes",
"reason": "Justified late"
}
}
}Add an email attachment as its own item#
POST/v1/relations/items.extractWrite
Adds one attachment of an .eml in the case file as an item of its own (checked by content like an upload; types storage refuses stay listed only). The lead and members. In the app only.
- Web app only
- Refused for API keys and connected apps. Employee relations works only in the Bizisy app: a case is confidential to its team.
- MCP tool
relations_items_extracton 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
case_idstringrequired1–64 characters.
item_idstringrequired1–64 characters.
indexintegerrequiredFrom 0 to 1000.
Returns
16 fields
idstringrequireddoc_nostringrequiredkind"record" | "file" | "statement"requiredrole"evidence" | "defence" | "statement" | "proof" | "opinion" | "other"requiredlabelstringrequiredonstring | nullrequiredsourceobject | nullrequired4 fields
modulestringrequiredtypestring (enum)requiredOne of:
timeclock_no_record,timeclock_late,timeoff,shifts,training_assigned,training_failed,documents,org_facts,earlier_case.refstringrequiredhashstringrequired
snapshotobject | nullrequiredfileobject | nullrequired6 fields
namestringrequiredcontent_typestringrequiredsizeintegerrequiredsha256string | nullrequiredpagesinteger | nullrequiredstatus"pending" | "ready"required
emailobject | nullrequired8 fields
fromstring | nullrequiredtostring | nullrequiredccstring | nullrequireddatestring | nullrequiredsubjectstring | nullrequiredtextstringrequiredtruncatedbooleanrequiredattachmentsobject[]required5 fields
indexintegerrequirednamestringrequiredcontent_typestringrequiredsizeintegerrequiredextracted_item_idstring | nullrequired
statementstring | nullrequiredconfirmed"unjustified" | "justified"requiredfrom_requestobject | nullrequired2 fields
request_idstringrequiredpersonobjectrequired2 fields
idstringrequirednamestringrequired
linked_byobjectrequired2 fields
user_idstringrequirednamestringrequired
linked_atstringrequiredremovedobject | nullrequired3 fields
atstringrequiredbystringrequiredreasonstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/items.extract \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"case_id":"c1","item_id":"i3","index":1}'const res = await fetch('https://api.bizisy.com/v1/relations/items.extract', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"case_id": "c1",
"item_id": "i3",
"index": 1
}),
});
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/relations/items.extract",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"case_id": "c1",
"item_id": "i3",
"index": 1,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "i4",
"doc_no": "D-4",
"kind": "file",
"role": "evidence",
"label": "No record, 2026-11-03, scheduled 09:00–18:00",
"on": "2026-11-03",
"source": null,
"snapshot": null,
"file": null,
"email": null,
"statement": null,
"confirmed": null,
"from_request": null,
"linked_by": {
"user_id": "u1",
"name": "Rui Lopes"
},
"linked_at": "2026-11-21T10:00:00.000Z",
"removed": null
}
}Download a file from a case file#
POST/v1/relations/items.downloadRead
A short-lived download link for one file in the case file (5 minutes). The team. In the app only.
- Web app only
- Refused for API keys and connected apps. Employee relations works only in the Bizisy app: a case is confidential to its team.
- MCP tool
relations_items_downloadon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
case_idstringrequired1–64 characters.
item_idstringrequired1–64 characters.
Returns
urlstringrequiredexpires_atstringrequirednamestringrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/items.download \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"case_id":"c1","item_id":"i2"}'const res = await fetch('https://api.bizisy.com/v1/relations/items.download', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"case_id": "c1",
"item_id": "i2"
}),
});
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/relations/items.download",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"case_id": "c1",
"item_id": "i2",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"url": "https://storage.example/file",
"expires_at": "2026-11-23T10:05:00.000Z",
"name": "D-2 defence.pdf"
}
}Ask someone for evidence#
POST/v1/relations/requests.sendWrite
Asks a person who is not on the case team (a manager, a witness) for documents or a written statement, in your words. They get a task in My workspace and an email that names only the case number; they never see the case. Not the person the case is about. Up to 20 open requests a case and 50 a lead a day. The lead only. In the app only.
- Web app only
- Refused for API keys and connected apps. Employee relations works only in the Bizisy app: a case is confidential to its team.
- MCP tool
relations_requests_sendon 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
case_idstringrequired1–64 characters.
to_person_idstringrequired1–64 characters.
askstringrequired5–2000 characters.
duestring | nullPattern
^\d{4}-\d{2}-\d{2}$. Defaultnull.
Returns
idstringrequiredtoobjectrequired2 fields
idstringrequirednamestringrequired
askstringrequiredduestring | nullrequiredstatus"open" | "answered" | "cancelled" | "expired"requiredatstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/requests.send \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"case_id": "c1",
"to_person_id": "p5",
"ask": "Upload the training invitations you sent in October."
}'const res = await fetch('https://api.bizisy.com/v1/relations/requests.send', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"case_id": "c1",
"to_person_id": "p5",
"ask": "Upload the training invitations you sent in October."
}),
});
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/relations/requests.send",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"case_id": "c1",
"to_person_id": "p5",
"ask": "Upload the training invitations you sent in October.",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "r1",
"to": {
"id": "p5",
"name": "Joao Pires"
},
"ask": "Upload the training invitations you sent in October.",
"due": null,
"status": "open",
"at": "2026-11-23T10:00:00.000Z"
}
}Cancel an evidence request#
POST/v1/relations/requests.cancelWrite
Cancels an open evidence request: the recipient sees it is no longer needed. The lead only. In the app only.
- Web app only
- Refused for API keys and connected apps. Employee relations works only in the Bizisy app: a case is confidential to its team.
- MCP tool
relations_requests_cancelon 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
case_idstringrequired1–64 characters.
request_idstringrequired1–64 characters.
Returns
idstringrequiredstatus"cancelled"required
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/requests.cancel \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"case_id":"c1","request_id":"r1"}'const res = await fetch('https://api.bizisy.com/v1/relations/requests.cancel', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"case_id": "c1",
"request_id": "r1"
}),
});
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/relations/requests.cancel",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"case_id": "c1",
"request_id": "r1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "r1",
"status": "cancelled"
}
}Requests from HR#
POST/v1/relations/me.requestsRead
The evidence requests HR sent you (open, and those answered or closed in the last 90 days): the case number, what is asked, by when, and what you sent. Never the case itself. In the app only.
- Web app only
- Refused for API keys and connected apps. Employee relations works only in the Bizisy app: a case is confidential to its team.
- MCP tool
relations_me_requestson My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
itemsobject[]required8 fields
idstringrequirednumberstringrequiredThe case number: the only thing about the case the recipient sees.
askstringrequiredduestring | nullrequiredstatus"open" | "answered" | "cancelled" | "expired"requiredanswered_atstring | nullrequiredsentintegerrequiredatstringrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/me.requests \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/relations/me.requests', {
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/relations/me.requests",
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": {
"items": [
{
"id": "r1",
"number": "ER-2026-0001",
"ask": "Upload the training invitations you sent in October.",
"due": "2026-11-30",
"status": "open",
"answered_at": null,
"sent": 0,
"at": "2026-11-23T10:00:00.000Z"
}
]
}
}Start uploading files for HR#
POST/v1/relations/me.requests.upload_urlWrite
Starts uploads for an open request from HR (at most 25 files, 5 at once; PDF, Word, ODT, text, images or .eml emails, up to 50 MB each). Then upload the bytes and send them with relations_me_requests_answer. In the app only.
- Web app only
- Refused for API keys and connected apps. Employee relations works only in the Bizisy app: a case is confidential to its team.
- MCP tool
relations_me_requests_upload_urlon My Workplace- 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
request_idstringrequired1–64 characters.
filesobject[]required1–25 items.
4 fields
namestringrequired1–255 characters.
sizeintegerrequiredFrom 1 to 50000000.
content_typestringrequired1–120 characters.
sha256stringrequiredPattern
^[0-9a-f]{64}$.
Returns
uploadsobject[]required4 fields
upload_idstringrequirednamestringrequireduploadobject | nullrequired3 fields
urlstringrequiredmethodstringrequiredheadersobjectrequired
expires_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/me.requests.upload_url \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"request_id": "r1",
"files": [
{
"name": "invite.eml",
"size": 900,
"content_type": "message/rfc822",
"sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
}
]
}'const res = await fetch('https://api.bizisy.com/v1/relations/me.requests.upload_url', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"request_id": "r1",
"files": [
{
"name": "invite.eml",
"size": 900,
"content_type": "message/rfc822",
"sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
}
]
}),
});
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/relations/me.requests.upload_url",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"request_id": "r1",
"files": [
{
"name": "invite.eml",
"size": 900,
"content_type": "message/rfc822",
"sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
},
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"uploads": [
{
"upload_id": "i9",
"name": "invite.eml",
"upload": null,
"expires_at": "2026-11-23T10:15:00.000Z"
}
]
}
}Send HR what they asked for#
POST/v1/relations/me.requests.answerWrite
Sends your answer to a request from HR: the files you uploaded (upload_ids) and/or a written statement. HR receives them with the time; you get a receipt. Once sent, an answer can't be changed here (ask HR). In the app only.
- Web app only
- Refused for API keys and connected apps. Employee relations works only in the Bizisy app: a case is confidential to its team.
- MCP tool
relations_me_requests_answeron My Workplace- 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
request_idstringrequired1–64 characters.
upload_idsstring[]1–64 characters. Up to 25 items.
statementstring | nullUp to 20000 characters. Default
null.
Returns
idstringrequirednumberstringrequiredanswered_atstringrequiredsentintegerrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/me.requests.answer \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"request_id":"r1","statement":"I sent them on 2 and 9 October."}'const res = await fetch('https://api.bizisy.com/v1/relations/me.requests.answer', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"request_id": "r1",
"statement": "I sent them on 2 and 9 October."
}),
});
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/relations/me.requests.answer",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"request_id": "r1",
"statement": "I sent them on 2 and 9 October.",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "r1",
"number": "ER-2026-0001",
"answered_at": "2026-11-23T10:00:00.000Z",
"sent": 1
}
}Download the case file as one PDF#
POST/v1/relations/bundle.exportWrite
Builds the case file as one PDF: a numbered index (D-numbers, dates, pages), the timeline, then every item in order (PDFs page by page, images, records, statements and emails as text, other files named with their SHA-256), each page stamped with the case number, its document and the page. Up to 2000 pages, 10 a case a day; it counts in the company's storage. Returns a 5-minute download link. The team. In the app only.
- Web app only
- Refused for API keys and connected apps. Employee relations works only in the Bizisy app: a case is confidential to its team.
- MCP tool
relations_bundle_exporton 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
case_idstringrequired1–64 characters.
language"en" | "pt" | "es" | "fr" | "de" | "it"Default
"en".include_removedfalseDefault
false.
Returns
urlstring | nullrequiredexpires_atstring | nullrequiredpagesintegerrequireditemsintegerrequirednamestringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/bundle.export \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"case_id":"c1","language":"pt"}'const res = await fetch('https://api.bizisy.com/v1/relations/bundle.export', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"case_id": "c1",
"language": "pt"
}),
});
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/relations/bundle.export",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"case_id": "c1",
"language": "pt",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"url": "https://storage.example/bundle",
"expires_at": "2026-11-23T10:05:00.000Z",
"pages": 12,
"items": 4,
"name": "ER-2026-0001 Case file.pdf"
}
}Employee relations settings#
POST/v1/relations/settings.getRead
Who can run cases, the rule packs on (Portugal, Spain; other countries use the fair-process fallback), the Spanish convenio faults with their severity, whether the Portuguese CBA doubles the sanction limits, the reminder days, the retention periods with the law's range, the fallback's own periods and what people see in My workspace. Owners and admins; ER staff read them. In the app only.
- Web app only
- Refused for API keys and connected apps. Employee relations works only in the Bizisy app: a case is confidential to its team.
- MCP tool
relations_settings_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
13 fields
staffobject[]required3 fields
user_idstringrequirednamestringrequiredemailstringrequired
packsobjectrequired2 fields
ptbooleanrequiredesbooleanrequired
convenioobject[]required3 fields
idstringrequiredlabelstringrequiredseverity"leve" | "grave" | "muy_grave"required
cba_doublebooleanrequiredreminder_offsetsinteger[]requiredremind_membersbooleanrequiredretentionobjectrequired4 fields
dismissal_monthsintegerrequiredsanction_monthsintegerrequiredsanction_yearsintegerrequiredno_sanction_monthsintegerrequired
retention_rangesobjectrequiredeu_defaultsobjectrequired2 fields
defence_daysintegerrequireddecision_daysintegerrequired
me_defaultobjectrequired3 fields
lettersbooleanrequiredanswerbooleanrequiredconsultbooleanrequired
wizardobjectrequired4 fields
staffbooleanrequiredrulesbooleanrequiredretentionbooleanrequiredaibooleanrequired
aiobjectrequired5 fields
availablebooleanrequiredThis server can run the case assistant (a model and file storage).
onbooleanrequiredoverseeobject[]requiredThe people who oversee it (AI Act Art. 26(2)).
2 fields
user_idstringrequirednamestringrequired
informed_onstring | nullrequiredThe day the company told its workers' representatives and workers that it is used (Art. 26(7)).
addendumobjectrequired3 fields
acceptedbooleanrequiredversionstringrequiredaccepted_versionstring | nullrequired
can_editbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/settings.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/relations/settings.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/relations/settings.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": {
"staff": [
{
"user_id": "u1",
"name": "Rui Lopes",
"email": "rui@acme.example"
}
],
"packs": {
"pt": true,
"es": true
},
"convenio": [],
"cba_double": false,
"reminder_offsets": [
7,
3,
1,
0
],
"remind_members": false,
"retention": {
"dismissal_months": 15,
"sanction_months": 12,
"sanction_years": 5,
"no_sanction_months": 12
},
"retention_ranges": {
"dismissal_months": [
15,
60
]
},
"eu_defaults": {
"defence_days": 10,
"decision_days": 30
},
"me_default": {
"letters": true,
"answer": true,
"consult": true
},
"wizard": {
"staff": true,
"rules": false,
"retention": false,
"ai": false
},
"ai": {
"available": true,
"on": true,
"oversee": [
{
"user_id": "u1",
"name": "Rui Lopes"
}
],
"informed_on": "2026-11-20",
"addendum": {
"accepted": true,
"version": "ai-6",
"accepted_version": "ai-6"
}
},
"can_edit": true
}
}Change Employee relations settings#
POST/v1/relations/settings.updateWrite
Changes Employee relations settings (only the fields given): staff (user ids who can open cases and be on teams; at most 200; owners, admins, HR or custom-role logins), packs ({pt, es}), convenio (the Spanish convenio faults: label and severity leve, grave or muy_grave), cba_double, reminder_offsets (days before a deadline, 0 = on the day; up to 6, 0–30), remind_members, retention (months and years within the law's range: dismissal 15–60 months after the employment ends; sanction 12–60 months after it ends and 1–10 years while employed; no sanction 12–60 months after closing), eu_defaults (the fallback's days to answer 1–60 and to decide 1–120), me_default, wizard (the setup steps done), ai (the case assistant: on, oversee — who oversees it, informed_on — the day the workers' representatives and workers were told; switching on needs the AI features addendum for case_assistant accepted by an owner, here with accept_addendum or before, the day they were told and someone overseeing it; off by default; off stops readings in progress and keeps the drafts). Owners and admins (accepting the addendum: owners). Supports dry_run. In the app only.
- Web app only
- Refused for API keys and connected apps. Employee relations works only in the Bizisy app: a case is confidential to its team.
- MCP tool
relations_settings_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
staffstring[]Up to 200 items.
packsobject2 fields
ptbooleanesboolean
convenioobject[]Up to 200 items.
3 fields
idstringUp to 20 characters.
labelstringrequired1–160 characters.
severity"leve" | "grave" | "muy_grave"required
cba_doublebooleanreminder_offsetsinteger[]From 0 to 30. Up to 6 items.
remind_membersbooleanretentionobject4 fields
dismissal_monthsintegerFrom 15 to 60.
sanction_monthsintegerFrom 12 to 60.
sanction_yearsintegerFrom 1 to 10.
no_sanction_monthsintegerFrom 12 to 60.
eu_defaultsobject2 fields
defence_daysintegerFrom 1 to 60.
decision_daysintegerFrom 1 to 120.
me_defaultobject3 fields
lettersbooleananswerbooleanconsultboolean
wizardobject4 fields
staffbooleanrulesbooleanretentionbooleanaiboolean
aiobject3 fields
onbooleanoverseestring[]User ids of the people who oversee the case assistant (default: who can run cases).
Up to 200 items.
informed_onstring | nullThe day the workers' representatives and workers were told it is used.
Pattern
^\d{4}-\d{2}-\d{2}$.
accept_addendumobjectOwners only: accept the AI features addendum for the case assistant (the version shown in Settings → Employee relations → AI reading).
2 fields
versionstringrequiredlang"en" | "de" | "es" | "fr" | "it" | "pt"Default
"en".
Returns
13 fields
staffobject[]required3 fields
user_idstringrequirednamestringrequiredemailstringrequired
packsobjectrequired2 fields
ptbooleanrequiredesbooleanrequired
convenioobject[]required3 fields
idstringrequiredlabelstringrequiredseverity"leve" | "grave" | "muy_grave"required
cba_doublebooleanrequiredreminder_offsetsinteger[]requiredremind_membersbooleanrequiredretentionobjectrequired4 fields
dismissal_monthsintegerrequiredsanction_monthsintegerrequiredsanction_yearsintegerrequiredno_sanction_monthsintegerrequired
retention_rangesobjectrequiredeu_defaultsobjectrequired2 fields
defence_daysintegerrequireddecision_daysintegerrequired
me_defaultobjectrequired3 fields
lettersbooleanrequiredanswerbooleanrequiredconsultbooleanrequired
wizardobjectrequired4 fields
staffbooleanrequiredrulesbooleanrequiredretentionbooleanrequiredaibooleanrequired
aiobjectrequired5 fields
availablebooleanrequiredThis server can run the case assistant (a model and file storage).
onbooleanrequiredoverseeobject[]requiredThe people who oversee it (AI Act Art. 26(2)).
2 fields
user_idstringrequirednamestringrequired
informed_onstring | nullrequiredThe day the company told its workers' representatives and workers that it is used (Art. 26(7)).
addendumobjectrequired3 fields
acceptedbooleanrequiredversionstringrequiredaccepted_versionstring | nullrequired
can_editbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/settings.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"accept_addendum": {
"version": "ai-6",
"lang": "pt"
},
"ai": {
"on": true,
"informed_on": "2026-11-20",
"oversee": [
"u1"
]
}
}'const res = await fetch('https://api.bizisy.com/v1/relations/settings.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"accept_addendum": {
"version": "ai-6",
"lang": "pt"
},
"ai": {
"on": true,
"informed_on": "2026-11-20",
"oversee": [
"u1"
]
}
}),
});
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/relations/settings.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"accept_addendum": {
"version": "ai-6",
"lang": "pt",
},
"ai": {
"on": True,
"informed_on": "2026-11-20",
"oversee": [
"u1",
],
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"staff": [
{
"user_id": "u1",
"name": "Rui Lopes",
"email": "rui@acme.example"
}
],
"packs": {
"pt": true,
"es": true
},
"convenio": [],
"cba_double": false,
"reminder_offsets": [
7,
3,
1,
0
],
"remind_members": false,
"retention": {
"dismissal_months": 15,
"sanction_months": 12,
"sanction_years": 5,
"no_sanction_months": 12
},
"retention_ranges": {
"dismissal_months": [
15,
60
]
},
"eu_defaults": {
"defence_days": 10,
"decision_days": 30
},
"me_default": {
"letters": true,
"answer": true,
"consult": true
},
"wizard": {
"staff": true,
"rules": false,
"retention": false,
"ai": false
},
"ai": {
"available": true,
"on": true,
"oversee": [
{
"user_id": "u1",
"name": "Rui Lopes"
}
],
"informed_on": "2026-11-20",
"addendum": {
"accepted": true,
"version": "ai-6",
"accepted_version": "ai-6"
}
},
"can_edit": true
}
}AI readings of a case#
POST/v1/relations/reads.listRead
A case's AI readings (newest first, at most 20) with their progress and drafts, the documents of the case file that can be read (PDF, Word, OpenDocument, text, pictures, emails, statements; up to 25 documents and 600 pages a reading; the person's answer and statements picked by default), whether reading is available (reason: unavailable on this server, off for the company, the AI features addendum not accepted), the company's AI credits and the readings left today (20 a case, 50 a user, 300 a company). The case team only. In the app only.
- Web app only
- Refused for API keys and connected apps. The case assistant works only in the Bizisy app, for the case team: a case is confidential to its team.
- MCP tool
relations_reads_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
case_idstringrequired1–64 characters.
Returns
9 fields
case_idstringrequiredavailablebooleanrequiredreason"unavailable" | "off" | "addendum"requiredcan_startbooleanrequiredcreditsobjectrequired2 fields
leftinteger | nullrequirednull: unlimited or not counted.
per_10_scanned_pages1required
left_todayintegerrequireddocumentsobject[]required8 fields
item_idstringrequireddoc_nostringrequiredlabelstringrequiredrolestringrequiredkindstring (enum)requiredOne of:
pdf,word,odt,text,image,email,statement.pagesinteger | nullrequiredPages (PDF) or an estimate (other documents).
readablebooleanrequiredsuggestedbooleanrequiredThe person's answer (defence) and statements: picked by default.
readingsobject[]required13 fields
idstringrequiredcase_idstringrequiredstatus"queued" | "reading" | "reducing" | "done" | "failed" | "cancelled"requiredfailurestring (enum)requiredOne of:
credits,unreadable,model,cancelled,unavailable,switched_off,timeout.progressobjectrequired4 fields
doneintegerrequiredtotalintegerrequiredunit"page" | "para" | "mixed"requiredextractingintegerrequiredDocuments still being opened.
sourcesobject[]required9 fields
item_idstringrequireddoc_nostringrequiredlabelstringrequiredkindstring (enum)requiredOne of:
pdf,word,odt,text,image,email,statement.pagesinteger | nullrequiredstatus"pending" | "ready" | "unreadable"requiredreason"type" | "damaged" | "empty" | "too_long"requiredunitsintegerrequiredocr_unitsintegerrequired
creditsobjectrequired2 fields
estimateintegerrequiredusedintegerrequired
modelstringrequiredprompt_vstringrequiredbyobjectrequired2 fields
user_idstringrequirednamestringrequired
created_atstringrequiredfinished_atstring | nullrequiredoutputobject | nullrequired15 fields
idstringrequiredstatus"draft" | "used" | "discarded"requiredai_generatedtruerequiredAn AI draft: a person checks it against the pages.
summaryobject[]requiredAt most 1,500 words, a citation on every sentence, ordered by the charged facts then general points.
3 fields
textstringrequiredcitesstring[]requiredCitations: "D-3 p. 12" (a page) or "D-3 ¶ 132" (a paragraph), each checked by code against the document.
fact_idstring | nullrequired
summary_editedstring | nullrequiredThe team's own wording of the summary, when edited.
argumentsobject[]required9 fields
idstringrequiredtextstringrequiredcategorystring (enum)requiredOne of:
procedural,deadline,facts_denied,justification_health,justification_family,justification_force_majeure,justification_transport,justification_other,proportionality,discrimination_retaliation,evidence_missing,other.fact_idsstring[]requiredcitesstring[]requiredCitations: "D-3 p. 12" (a page) or "D-3 ¶ 132" (a paragraph), each checked by code against the document.
quotesobject[]required3 fields
citestringrequiredtextstringrequiredfoundbooleanrequired
timesintegerrequiredHow many times the point is made.
citation_foundbooleanrequiredfalse: no citation could be checked ("citation not found").
answeredbooleanrequired
stepsobject[]required10 fields
idstringrequiredkind"witness" | "document" | "expert" | "other"requiredtextstringrequiredwitnessstring | nullrequiredfor_fact_idsstring[]requiredcitesstring[]requiredCitations: "D-3 p. 12" (a page) or "D-3 ¶ 132" (a paragraph), each checked by code against the document.
timesintegerrequiredstatus"open" | "done" | "refused" | "not_needed"requiredreasonstring | nullrequiredbeyond_capbooleanrequiredPortugal: beyond 3 witnesses a fact or 10 in total (CT 356(4)).
attachmentsobject[]required3 fields
idstringrequiredtextstringrequiredcitesstring[]requiredCitations: "D-3 p. 12" (a page) or "D-3 ¶ 132" (a paragraph), each checked by code against the document.
coverageobjectrequired7 fields
unitsintegerrequiredusedintegerrequiredunusedobject[]requiredPages or paragraphs no item came from: open them.
4 fields
docstringrequiredkind"page" | "para"requiredfromintegerrequiredtointegerrequired
ocr_failedobject[]required4 fields
docstringrequiredkind"page" | "para"requiredfromintegerrequiredtointegerrequired
not_readobject[]required4 fields
docstringrequiredkind"page" | "para"requiredfromintegerrequiredtointegerrequired
unreadableobject[]required2 fields
docstringrequiredreason"type" | "damaged" | "empty" | "too_long"required
truncatedobject[]required4 fields
docstringrequiredkind"page" | "para"requiredfromintegerrequiredtointegerrequired
guardobjectrequired5 fields
cites_droppedintegerrequiredquotes_droppedintegerrequireditems_droppedintegerrequiredsentences_droppedintegerrequiredoutcome_droppedintegerrequired
mergedbooleanrequiredfalse: the merge failed; arguments were merged by code and there is no summary.
truncatedobject | nullrequiredThe lists were cut to keep the draft under its size limit: how many there were.
2 fields
argumentsintegerrequiredstepsintegerrequired
modelstringrequiredprompt_vstringrequiredcreated_atstringrequired
modelstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/reads.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"case_id":"c1"}'const res = await fetch('https://api.bizisy.com/v1/relations/reads.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"case_id": "c1"
}),
});
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/relations/reads.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"case_id": "c1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"case_id": "c1",
"available": true,
"reason": null,
"can_start": true,
"credits": {
"left": 61200,
"per_10_scanned_pages": 1
},
"left_today": 19,
"documents": [
{
"item_id": "i2",
"doc_no": "D-2",
"label": "defence.pdf",
"role": "defence",
"kind": "pdf",
"pages": 48,
"readable": true,
"suggested": true
}
],
"readings": [
{
"id": "rd1",
"case_id": "c1",
"status": "done",
"failure": null,
"progress": {
"done": 48,
"total": 48,
"unit": "page",
"extracting": 0
},
"sources": [
{
"item_id": "i2",
"doc_no": "D-2",
"label": "defence.pdf",
"kind": "pdf",
"pages": 48,
"status": "ready",
"reason": null,
"units": 48,
"ocr_units": 0
}
],
"credits": {
"estimate": 11,
"used": 9
},
"model": "gemini-3.5-flash",
"prompt_v": "case-read-1",
"by": {
"user_id": "u1",
"name": "Rui Lopes"
},
"created_at": "2026-11-23T10:00:00.000Z",
"finished_at": "2026-11-23T10:05:00.000Z",
"output": {
"id": "o1",
"status": "draft",
"ai_generated": true,
"summary": [
{
"text": "The employee says the absence on 3 November was due to health reasons, with a medical certificate.",
"cites": [
"D-2 p. 3",
"D-2 p. 41"
],
"fact_id": "f1"
}
],
"summary_edited": null,
"arguments": [
{
"id": "a1",
"text": "Health reasons on 3 November (a medical certificate).",
"category": "justification_health",
"fact_ids": [
"f1"
],
"cites": [
"D-2 p. 3",
"D-2 p. 41"
],
"quotes": [
{
"cite": "D-2 p. 3",
"text": "estive doente no dia 3",
"found": true
}
],
"times": 2,
"citation_found": true,
"answered": false
}
],
"steps": [
{
"id": "s1",
"kind": "witness",
"text": "Hear Maria Silva about 3 November.",
"witness": "Maria Silva",
"for_fact_ids": [
"f1"
],
"cites": [
"D-2 p. 9"
],
"times": 1,
"status": "open",
"reason": null,
"beyond_cap": false
}
],
"attachments": [
{
"id": "d1",
"text": "Medical certificate",
"cites": [
"D-2 p. 41"
]
}
],
"coverage": {
"units": 48,
"used": 30,
"unused": [
{
"doc": "D-2",
"kind": "page",
"from": 42,
"to": 48
}
],
"ocr_failed": [],
"not_read": [],
"unreadable": [],
"truncated": []
},
"guard": {
"cites_dropped": 0,
"quotes_dropped": 0,
"items_dropped": 0,
"sentences_dropped": 0,
"outcome_dropped": 0
},
"merged": true,
"truncated": null,
"model": "gemini-3.5-flash",
"prompt_v": "case-read-1",
"created_at": "2026-11-23T10:05:00.000Z"
}
}
],
"model": "gemini-3.5-flash"
}
}Read case documents with AI#
POST/v1/relations/reads.startWrite
Starts an AI reading of documents in a case file (item_ids; default the person's answer and statements): the text of each page (scanned pages by Google Cloud Document AI in the EU) goes, about 15 pages at a time, to a language model on Google Cloud Vertex AI in the EU, then one call merges what was found. The result is a draft for the team: a summary in which every sentence cites its pages (at most 1,500 words), the arguments (with how many times each is made, linked to the charged facts) and the evidence steps asked for, every quote checked word for word against its page by Bizisy, and the pages that gave nothing. It never proposes a finding, an outcome or a sanction and never assesses the person. It runs in the background (minutes for a long answer): follow it with relations.reads.get. Credits: a dry run gives the estimate and the balance; each step holds its worst case first; about 1 credit per 5 pages of text, +1 per 10 scanned pages; a reading that fails charges nothing. One reading at a time per case; at most 25 documents and 600 pages; 20 a case, 50 a user and 300 a company a day. The lead and members, when the company switched AI reading on and an owner accepted the AI features addendum for it. In the app only.
- Web app only
- Refused for API keys and connected apps. The case assistant works only in the Bizisy app, for the case team: a case is confidential to its team.
- MCP tool
relations_reads_starton 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
case_idstringrequired1–64 characters.
item_idsstring[]Default: the person's answer and statements.
1–64 characters. Up to 25 items.
Returns
case_idstringrequiredreadingobject | nullrequirednull on a dry run.
13 fields
idstringrequiredcase_idstringrequiredstatus"queued" | "reading" | "reducing" | "done" | "failed" | "cancelled"requiredfailurestring (enum)requiredOne of:
credits,unreadable,model,cancelled,unavailable,switched_off,timeout.progressobjectrequired4 fields
doneintegerrequiredtotalintegerrequiredunit"page" | "para" | "mixed"requiredextractingintegerrequiredDocuments still being opened.
sourcesobject[]required9 fields
item_idstringrequireddoc_nostringrequiredlabelstringrequiredkindstring (enum)requiredOne of:
pdf,word,odt,text,image,email,statement.pagesinteger | nullrequiredstatus"pending" | "ready" | "unreadable"requiredreason"type" | "damaged" | "empty" | "too_long"requiredunitsintegerrequiredocr_unitsintegerrequired
creditsobjectrequired2 fields
estimateintegerrequiredusedintegerrequired
modelstringrequiredprompt_vstringrequiredbyobjectrequired2 fields
user_idstringrequirednamestringrequired
created_atstringrequiredfinished_atstring | nullrequiredoutputobject | nullrequired15 fields
idstringrequiredstatus"draft" | "used" | "discarded"requiredai_generatedtruerequiredAn AI draft: a person checks it against the pages.
summaryobject[]requiredAt most 1,500 words, a citation on every sentence, ordered by the charged facts then general points.
3 fields
textstringrequiredcitesstring[]requiredCitations: "D-3 p. 12" (a page) or "D-3 ¶ 132" (a paragraph), each checked by code against the document.
fact_idstring | nullrequired
summary_editedstring | nullrequiredThe team's own wording of the summary, when edited.
argumentsobject[]required9 fields
idstringrequiredtextstringrequiredcategorystring (enum)requiredOne of:
procedural,deadline,facts_denied,justification_health,justification_family,justification_force_majeure,justification_transport,justification_other,proportionality,discrimination_retaliation,evidence_missing,other.fact_idsstring[]requiredcitesstring[]requiredCitations: "D-3 p. 12" (a page) or "D-3 ¶ 132" (a paragraph), each checked by code against the document.
quotesobject[]required3 fields
citestringrequiredtextstringrequiredfoundbooleanrequired
timesintegerrequiredHow many times the point is made.
citation_foundbooleanrequiredfalse: no citation could be checked ("citation not found").
answeredbooleanrequired
stepsobject[]required10 fields
idstringrequiredkind"witness" | "document" | "expert" | "other"requiredtextstringrequiredwitnessstring | nullrequiredfor_fact_idsstring[]requiredcitesstring[]requiredCitations: "D-3 p. 12" (a page) or "D-3 ¶ 132" (a paragraph), each checked by code against the document.
timesintegerrequiredstatus"open" | "done" | "refused" | "not_needed"requiredreasonstring | nullrequiredbeyond_capbooleanrequiredPortugal: beyond 3 witnesses a fact or 10 in total (CT 356(4)).
attachmentsobject[]required3 fields
idstringrequiredtextstringrequiredcitesstring[]requiredCitations: "D-3 p. 12" (a page) or "D-3 ¶ 132" (a paragraph), each checked by code against the document.
coverageobjectrequired7 fields
unitsintegerrequiredusedintegerrequiredunusedobject[]requiredPages or paragraphs no item came from: open them.
4 fields
docstringrequiredkind"page" | "para"requiredfromintegerrequiredtointegerrequired
ocr_failedobject[]required4 fields
docstringrequiredkind"page" | "para"requiredfromintegerrequiredtointegerrequired
not_readobject[]required4 fields
docstringrequiredkind"page" | "para"requiredfromintegerrequiredtointegerrequired
unreadableobject[]required2 fields
docstringrequiredreason"type" | "damaged" | "empty" | "too_long"required
truncatedobject[]required4 fields
docstringrequiredkind"page" | "para"requiredfromintegerrequiredtointegerrequired
guardobjectrequired5 fields
cites_droppedintegerrequiredquotes_droppedintegerrequireditems_droppedintegerrequiredsentences_droppedintegerrequiredoutcome_droppedintegerrequired
mergedbooleanrequiredfalse: the merge failed; arguments were merged by code and there is no summary.
truncatedobject | nullrequiredThe lists were cut to keep the draft under its size limit: how many there were.
2 fields
argumentsintegerrequiredstepsintegerrequired
modelstringrequiredprompt_vstringrequiredcreated_atstringrequired
estimateintegerrequiredpagesintegerrequiredcredits_leftinteger | nullrequireddocumentsstring[]requiredThe case document numbers to be read.
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/reads.start \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"case_id":"c1","item_ids":["i2"]}'const res = await fetch('https://api.bizisy.com/v1/relations/reads.start', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"case_id": "c1",
"item_ids": [
"i2"
]
}),
});
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/relations/reads.start",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"case_id": "c1",
"item_ids": [
"i2",
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"case_id": "c1",
"reading": {
"id": "rd1",
"case_id": "c1",
"status": "queued",
"failure": null,
"progress": {
"done": 0,
"total": 48,
"unit": "page",
"extracting": 1
},
"sources": [
{
"item_id": "i2",
"doc_no": "D-2",
"label": "defence.pdf",
"kind": "pdf",
"pages": 48,
"status": "ready",
"reason": null,
"units": 48,
"ocr_units": 0
}
],
"credits": {
"estimate": 11,
"used": 9
},
"model": "gemini-3.5-flash",
"prompt_v": "case-read-1",
"by": {
"user_id": "u1",
"name": "Rui Lopes"
},
"created_at": "2026-11-23T10:00:00.000Z",
"finished_at": null,
"output": null
},
"estimate": 11,
"pages": 48,
"credits_left": 61200,
"documents": [
"D-2"
]
}
}An AI reading of a case#
POST/v1/relations/reads.getRead
One AI reading: its progress ("page 64 of 148"), the documents it reads and their state, the credits estimated and used, and when done its draft (summary with citations, arguments, evidence steps, attachments, page coverage), marked ai_generated. The case team only. In the app only.
- Web app only
- Refused for API keys and connected apps. The case assistant works only in the Bizisy app, for the case team: a case is confidential to its team.
- MCP tool
relations_reads_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
case_idstringrequired1–64 characters.
read_idstringrequired1–64 characters.
Returns
13 fields
idstringrequiredcase_idstringrequiredstatus"queued" | "reading" | "reducing" | "done" | "failed" | "cancelled"requiredfailurestring (enum)requiredOne of:
credits,unreadable,model,cancelled,unavailable,switched_off,timeout.progressobjectrequired4 fields
doneintegerrequiredtotalintegerrequiredunit"page" | "para" | "mixed"requiredextractingintegerrequiredDocuments still being opened.
sourcesobject[]required9 fields
item_idstringrequireddoc_nostringrequiredlabelstringrequiredkindstring (enum)requiredOne of:
pdf,word,odt,text,image,email,statement.pagesinteger | nullrequiredstatus"pending" | "ready" | "unreadable"requiredreason"type" | "damaged" | "empty" | "too_long"requiredunitsintegerrequiredocr_unitsintegerrequired
creditsobjectrequired2 fields
estimateintegerrequiredusedintegerrequired
modelstringrequiredprompt_vstringrequiredbyobjectrequired2 fields
user_idstringrequirednamestringrequired
created_atstringrequiredfinished_atstring | nullrequiredoutputobject | nullrequired15 fields
idstringrequiredstatus"draft" | "used" | "discarded"requiredai_generatedtruerequiredAn AI draft: a person checks it against the pages.
summaryobject[]requiredAt most 1,500 words, a citation on every sentence, ordered by the charged facts then general points.
3 fields
textstringrequiredcitesstring[]requiredCitations: "D-3 p. 12" (a page) or "D-3 ¶ 132" (a paragraph), each checked by code against the document.
fact_idstring | nullrequired
summary_editedstring | nullrequiredThe team's own wording of the summary, when edited.
argumentsobject[]required9 fields
idstringrequiredtextstringrequiredcategorystring (enum)requiredOne of:
procedural,deadline,facts_denied,justification_health,justification_family,justification_force_majeure,justification_transport,justification_other,proportionality,discrimination_retaliation,evidence_missing,other.fact_idsstring[]requiredcitesstring[]requiredCitations: "D-3 p. 12" (a page) or "D-3 ¶ 132" (a paragraph), each checked by code against the document.
quotesobject[]required3 fields
citestringrequiredtextstringrequiredfoundbooleanrequired
timesintegerrequiredHow many times the point is made.
citation_foundbooleanrequiredfalse: no citation could be checked ("citation not found").
answeredbooleanrequired
stepsobject[]required10 fields
idstringrequiredkind"witness" | "document" | "expert" | "other"requiredtextstringrequiredwitnessstring | nullrequiredfor_fact_idsstring[]requiredcitesstring[]requiredCitations: "D-3 p. 12" (a page) or "D-3 ¶ 132" (a paragraph), each checked by code against the document.
timesintegerrequiredstatus"open" | "done" | "refused" | "not_needed"requiredreasonstring | nullrequiredbeyond_capbooleanrequiredPortugal: beyond 3 witnesses a fact or 10 in total (CT 356(4)).
attachmentsobject[]required3 fields
idstringrequiredtextstringrequiredcitesstring[]requiredCitations: "D-3 p. 12" (a page) or "D-3 ¶ 132" (a paragraph), each checked by code against the document.
coverageobjectrequired7 fields
unitsintegerrequiredusedintegerrequiredunusedobject[]requiredPages or paragraphs no item came from: open them.
4 fields
docstringrequiredkind"page" | "para"requiredfromintegerrequiredtointegerrequired
ocr_failedobject[]required4 fields
docstringrequiredkind"page" | "para"requiredfromintegerrequiredtointegerrequired
not_readobject[]required4 fields
docstringrequiredkind"page" | "para"requiredfromintegerrequiredtointegerrequired
unreadableobject[]required2 fields
docstringrequiredreason"type" | "damaged" | "empty" | "too_long"required
truncatedobject[]required4 fields
docstringrequiredkind"page" | "para"requiredfromintegerrequiredtointegerrequired
guardobjectrequired5 fields
cites_droppedintegerrequiredquotes_droppedintegerrequireditems_droppedintegerrequiredsentences_droppedintegerrequiredoutcome_droppedintegerrequired
mergedbooleanrequiredfalse: the merge failed; arguments were merged by code and there is no summary.
truncatedobject | nullrequiredThe lists were cut to keep the draft under its size limit: how many there were.
2 fields
argumentsintegerrequiredstepsintegerrequired
modelstringrequiredprompt_vstringrequiredcreated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/reads.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"case_id":"c1","read_id":"rd1"}'const res = await fetch('https://api.bizisy.com/v1/relations/reads.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"case_id": "c1",
"read_id": "rd1"
}),
});
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/relations/reads.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"case_id": "c1",
"read_id": "rd1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "rd1",
"case_id": "c1",
"status": "done",
"failure": null,
"progress": {
"done": 48,
"total": 48,
"unit": "page",
"extracting": 0
},
"sources": [
{
"item_id": "i2",
"doc_no": "D-2",
"label": "defence.pdf",
"kind": "pdf",
"pages": 48,
"status": "ready",
"reason": null,
"units": 48,
"ocr_units": 0
}
],
"credits": {
"estimate": 11,
"used": 9
},
"model": "gemini-3.5-flash",
"prompt_v": "case-read-1",
"by": {
"user_id": "u1",
"name": "Rui Lopes"
},
"created_at": "2026-11-23T10:00:00.000Z",
"finished_at": "2026-11-23T10:05:00.000Z",
"output": {
"id": "o1",
"status": "draft",
"ai_generated": true,
"summary": [
{
"text": "The employee says the absence on 3 November was due to health reasons, with a medical certificate.",
"cites": [
"D-2 p. 3",
"D-2 p. 41"
],
"fact_id": "f1"
}
],
"summary_edited": null,
"arguments": [
{
"id": "a1",
"text": "Health reasons on 3 November (a medical certificate).",
"category": "justification_health",
"fact_ids": [
"f1"
],
"cites": [
"D-2 p. 3",
"D-2 p. 41"
],
"quotes": [
{
"cite": "D-2 p. 3",
"text": "estive doente no dia 3",
"found": true
}
],
"times": 2,
"citation_found": true,
"answered": false
}
],
"steps": [
{
"id": "s1",
"kind": "witness",
"text": "Hear Maria Silva about 3 November.",
"witness": "Maria Silva",
"for_fact_ids": [
"f1"
],
"cites": [
"D-2 p. 9"
],
"times": 1,
"status": "open",
"reason": null,
"beyond_cap": false
}
],
"attachments": [
{
"id": "d1",
"text": "Medical certificate",
"cites": [
"D-2 p. 41"
]
}
],
"coverage": {
"units": 48,
"used": 30,
"unused": [
{
"doc": "D-2",
"kind": "page",
"from": 42,
"to": 48
}
],
"ocr_failed": [],
"not_read": [],
"unreadable": [],
"truncated": []
},
"guard": {
"cites_dropped": 0,
"quotes_dropped": 0,
"items_dropped": 0,
"sentences_dropped": 0,
"outcome_dropped": 0
},
"merged": true,
"truncated": null,
"model": "gemini-3.5-flash",
"prompt_v": "case-read-1",
"created_at": "2026-11-23T10:05:00.000Z"
}
}
}Cancel an AI reading#
POST/v1/relations/reads.cancelWrite
Stops an AI reading in progress. The parts already read stay charged (what the model read cost); steps in flight are not charged. The lead and members. In the app only.
- Web app only
- Refused for API keys and connected apps. The case assistant works only in the Bizisy app, for the case team: a case is confidential to its team.
- MCP tool
relations_reads_cancelon 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
case_idstringrequired1–64 characters.
read_idstringrequired1–64 characters.
Returns
case_idstringrequiredcancelledbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/reads.cancel \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"case_id":"c1","read_id":"rd1"}'const res = await fetch('https://api.bizisy.com/v1/relations/reads.cancel', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"case_id": "c1",
"read_id": "rd1"
}),
});
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/relations/reads.cancel",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"case_id": "c1",
"read_id": "rd1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"case_id": "c1",
"cancelled": true
}
}Work with an AI reading's draft#
POST/v1/relations/ai.updateWrite
What the team does with an AI reading's draft, recorded in the AI log: tick arguments as answered (arguments: [{id, answered}]), set each evidence step asked for to done, refused (reason required: the written reasons, CT 356(1)) or not needed (steps: [{id, status, reason}]), keep its own wording of the summary (summary_edited; the edit ratio is logged), and say whether the draft was used or discarded (status). The lead and members. In the app only.
- Web app only
- Refused for API keys and connected apps. The case assistant works only in the Bizisy app, for the case team: a case is confidential to its team.
- MCP tool
relations_ai_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
case_idstringrequired1–64 characters.
output_idstringrequired1–64 characters.
argumentsobject[]Up to 500 items.
2 fields
idstringrequiredUp to 20 characters.
answeredbooleanrequired
stepsobject[]Up to 500 items.
3 fields
idstringrequiredUp to 20 characters.
status"open" | "done" | "refused" | "not_needed"requiredreasonstring | nullUp to 2000 characters. Default
null.
summary_editedstring | nullUp to 20000 characters.
status"draft" | "used" | "discarded"
Returns
case_idstringrequiredoutputobjectrequired15 fields
idstringrequiredstatus"draft" | "used" | "discarded"requiredai_generatedtruerequiredAn AI draft: a person checks it against the pages.
summaryobject[]requiredAt most 1,500 words, a citation on every sentence, ordered by the charged facts then general points.
3 fields
textstringrequiredcitesstring[]requiredCitations: "D-3 p. 12" (a page) or "D-3 ¶ 132" (a paragraph), each checked by code against the document.
fact_idstring | nullrequired
summary_editedstring | nullrequiredThe team's own wording of the summary, when edited.
argumentsobject[]required9 fields
idstringrequiredtextstringrequiredcategorystring (enum)requiredOne of:
procedural,deadline,facts_denied,justification_health,justification_family,justification_force_majeure,justification_transport,justification_other,proportionality,discrimination_retaliation,evidence_missing,other.fact_idsstring[]requiredcitesstring[]requiredCitations: "D-3 p. 12" (a page) or "D-3 ¶ 132" (a paragraph), each checked by code against the document.
quotesobject[]required3 fields
citestringrequiredtextstringrequiredfoundbooleanrequired
timesintegerrequiredHow many times the point is made.
citation_foundbooleanrequiredfalse: no citation could be checked ("citation not found").
answeredbooleanrequired
stepsobject[]required10 fields
idstringrequiredkind"witness" | "document" | "expert" | "other"requiredtextstringrequiredwitnessstring | nullrequiredfor_fact_idsstring[]requiredcitesstring[]requiredCitations: "D-3 p. 12" (a page) or "D-3 ¶ 132" (a paragraph), each checked by code against the document.
timesintegerrequiredstatus"open" | "done" | "refused" | "not_needed"requiredreasonstring | nullrequiredbeyond_capbooleanrequiredPortugal: beyond 3 witnesses a fact or 10 in total (CT 356(4)).
attachmentsobject[]required3 fields
idstringrequiredtextstringrequiredcitesstring[]requiredCitations: "D-3 p. 12" (a page) or "D-3 ¶ 132" (a paragraph), each checked by code against the document.
coverageobjectrequired7 fields
unitsintegerrequiredusedintegerrequiredunusedobject[]requiredPages or paragraphs no item came from: open them.
4 fields
docstringrequiredkind"page" | "para"requiredfromintegerrequiredtointegerrequired
ocr_failedobject[]required4 fields
docstringrequiredkind"page" | "para"requiredfromintegerrequiredtointegerrequired
not_readobject[]required4 fields
docstringrequiredkind"page" | "para"requiredfromintegerrequiredtointegerrequired
unreadableobject[]required2 fields
docstringrequiredreason"type" | "damaged" | "empty" | "too_long"required
truncatedobject[]required4 fields
docstringrequiredkind"page" | "para"requiredfromintegerrequiredtointegerrequired
guardobjectrequired5 fields
cites_droppedintegerrequiredquotes_droppedintegerrequireditems_droppedintegerrequiredsentences_droppedintegerrequiredoutcome_droppedintegerrequired
mergedbooleanrequiredfalse: the merge failed; arguments were merged by code and there is no summary.
truncatedobject | nullrequiredThe lists were cut to keep the draft under its size limit: how many there were.
2 fields
argumentsintegerrequiredstepsintegerrequired
modelstringrequiredprompt_vstringrequiredcreated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/ai.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"case_id": "c1",
"output_id": "o1",
"steps": [
{
"id": "s1",
"status": "refused",
"reason": "Not present that day."
}
],
"status": "used"
}'const res = await fetch('https://api.bizisy.com/v1/relations/ai.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"case_id": "c1",
"output_id": "o1",
"steps": [
{
"id": "s1",
"status": "refused",
"reason": "Not present that day."
}
],
"status": "used"
}),
});
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/relations/ai.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"case_id": "c1",
"output_id": "o1",
"steps": [
{
"id": "s1",
"status": "refused",
"reason": "Not present that day.",
},
],
"status": "used",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"case_id": "c1",
"output": {
"id": "o1",
"status": "draft",
"ai_generated": true,
"summary": [
{
"text": "The employee says the absence on 3 November was due to health reasons, with a medical certificate.",
"cites": [
"D-2 p. 3",
"D-2 p. 41"
],
"fact_id": "f1"
}
],
"summary_edited": null,
"arguments": [
{
"id": "a1",
"text": "Health reasons on 3 November (a medical certificate).",
"category": "justification_health",
"fact_ids": [
"f1"
],
"cites": [
"D-2 p. 3",
"D-2 p. 41"
],
"quotes": [
{
"cite": "D-2 p. 3",
"text": "estive doente no dia 3",
"found": true
}
],
"times": 2,
"citation_found": true,
"answered": true
}
],
"steps": [
{
"id": "s1",
"kind": "witness",
"text": "Hear Maria Silva about 3 November.",
"witness": "Maria Silva",
"for_fact_ids": [
"f1"
],
"cites": [
"D-2 p. 9"
],
"times": 1,
"status": "open",
"reason": null,
"beyond_cap": false
}
],
"attachments": [
{
"id": "d1",
"text": "Medical certificate",
"cites": [
"D-2 p. 41"
]
}
],
"coverage": {
"units": 48,
"used": 30,
"unused": [
{
"doc": "D-2",
"kind": "page",
"from": 42,
"to": 48
}
],
"ocr_failed": [],
"not_read": [],
"unreadable": [],
"truncated": []
},
"guard": {
"cites_dropped": 0,
"quotes_dropped": 0,
"items_dropped": 0,
"sentences_dropped": 0,
"outcome_dropped": 0
},
"merged": true,
"truncated": null,
"model": "gemini-3.5-flash",
"prompt_v": "case-read-1",
"created_at": "2026-11-23T10:05:00.000Z"
}
}
}AI log of a case#
POST/v1/relations/ai.logRead
Every use of the case assistant in a case (AI Act Art. 12): who, when, which documents (numbers and SHA-256), the model and prompt version, the outcome, the credits, and what the team did with the draft (used, edited with the edit ratio, discarded). Kept with the case and at least six months. The case team only. In the app only.
- Web app only
- Refused for API keys and connected apps. The case assistant works only in the Bizisy app, for the case team: a case is confidential to its team.
- MCP tool
relations_ai_logon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
case_idstringrequired1–64 characters.
Returns
case_idstringrequiredrowsobject[]required15 fields
idstringrequiredatstringrequiredbyobjectrequired2 fields
user_idstringrequirednamestringrequired
run"reading"requiredinputsobject[]required3 fields
doc_nostringrequiredsha256stringrequiredunitsintegerrequired
modelstringrequiredreduce_modelstringrequiredprompt_vstringrequiredoutcome"running" | "done" | "failed" | "cancelled"requiredcreditsintegerrequiredhuman_action"used" | "edited" | "discarded"requirededit_rationumber | nullrequiredacted_bystring | nullrequiredacted_atstring | nullrequiredkeep_untilstringrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/relations/ai.log \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"case_id":"c1"}'const res = await fetch('https://api.bizisy.com/v1/relations/ai.log', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"case_id": "c1"
}),
});
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/relations/ai.log",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"case_id": "c1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"case_id": "c1",
"rows": [
{
"id": "rd1",
"at": "2026-11-23T10:00:00.000Z",
"by": {
"user_id": "u1",
"name": "Rui Lopes"
},
"run": "reading",
"inputs": [
{
"doc_no": "D-2",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"units": 48
}
],
"model": "gemini-3.5-flash",
"reduce_model": "gemini-3.5-flash",
"prompt_v": "case-read-1",
"outcome": "done",
"credits": 9,
"human_action": null,
"edit_ratio": null,
"acted_by": null,
"acted_at": null,
"keep_until": "2027-05-23"
}
]
}
}Something missing or wrong on this page? Write to hello@bizisy.com.