API reference
Documents
Company and person documents: list, upload, change, download and delete; categories.
58 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.
List documents#
POST/v1/documents/listRead
Lists documents you can see, newest first (or largest first with sort=largest): person documents (contracts, addenda, certificates, ID copies…) and company documents (handbook, policies…). Filters: person_id (one person's documents), scope (person, company or all), category, q (words in the title). Owners, admins and HR see every document; others see the company documents shared with them and their own. Person documents are private: through an API key or an AI assistant, other people's documents come as metadata only (title, category, date, size; access = metadata), never their contents.
- Who can call it
- Manage key any Manage role
- Keys and apps
- Other people's documents come as metadata only.
- MCP tool
documents_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
person_idstringscope"person" | "company" | "all"Default all (person_id implies person).
categorystringUp to 60 characters.
qstringWords that must all appear in the title (case-insensitive).
Up to 100 characters.
idsstring[]Only these documents (e.g. a renewal's document_ids); those you can't see are left out.
1–64 characters. Up to 50 items.
sort"newest" | "largest"limitintegerDefault 500.
From 1 to 500.
Returns
documentsobject[]required19 fields
idstringrequiredtitlestringrequiredcategorystringrequiredsubjectobjectrequired3 fields (one of several shapes)
Option 1
kind"person"requiredpersonobject | nullrequired2 fields
idstringrequirednamestringrequired
Option 2
kind"company"required
visibilitystring (enum)requiredOne of:
hr,hr_person,hr_person_manager,everyone,managers,hr,accountant.uploaded_by"hr" | "self"requiredself: the person added it themself ("From me", or a custom field they fill in).
fieldobject | nullrequiredA custom file field's file (
org_fields_list): its visibility follows the field's tier; replace or remove it through the field.2 fields
keystringrequiredlabelstringrequired
expires_onstring | nullrequirednotesstring | nullrequirednull when you only see metadata.
fileobjectrequired4 fields
namestring | nullrequiredThe original file name; null when you only see metadata.
sizeintegerrequiredcontent_typestringrequiredpreviewablebooleanrequiredThe web app can show it (PDF, PNG, JPEG, WebP).
access"full" | "metadata"requiredmetadata: title, category, date and size only (no notes, no download): API keys and AI assistants never get the contents of other people's documents.
signed_fromobject | nullrequiredA signed copy or signature audit trail the e-signature tool handed back: the original document. null for other documents.
2 fields
document_idstringrequiredkind"signed" | "audit_trail"required
signatureobject | nullThe latest signature request (lists only): status, level and how many have signed.
6 fields
idstringrequiredstatusstring (enum)requiredOne of:
queued,sending,ongoing,done,declined,expired,canceled,failed.level"simple" | "advanced" | "qualified"requiredsignedintegerrequiredtotalintegerrequiredyour_turnbooleanrequiredYou are the signer the e-signature tool is waiting for (check your email from it).
generated_fromobject | nullMade from a document template: which one, its version, language and style (
documents_templates_get). null for uploaded documents.4 fields
template_idstringrequiredversionintegerrequiredlanguagestringrequiredstyle"international" | "continental"requiredThe document style it was made in (international or continental); null for documents made before styles existed.
draftobject | nullA draft only HR sees until it is sent (
documents_prepared_decide): the prepared document, and who will see it once sent. null otherwise.2 fields
prepared_idstringrequiredvisibility"hr" | "hr_person" | "hr_person_manager"required
deliveryobject | nullProof of delivery of a written statement or change notice: when it was sent, first opened and its receipt confirmed (or handed over on paper). null for other documents.
5 fields
method"electronic" | "print"requiredsent_atstringrequiredopened_atstring | nullrequiredacknowledged_atstring | nullrequiredhanded_over_onstring | nullrequired
status"pending" | "ready"requiredcreated_atstringrequiredupdated_atstringrequired
categoriesstring[]requiredEvery category in use for new documents: the starter list and your own.
max_file_bytesintegerrequiredThe largest file allowed (Settings → Storage).
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"person_id": "p1",
"category": "Contract",
"q": "contract",
"sort": "largest",
"limit": 5
}'const res = await fetch('https://api.bizisy.com/v1/documents/list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"person_id": "p1",
"category": "Contract",
"q": "contract",
"sort": "largest",
"limit": 5
}),
});
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/documents/list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"person_id": "p1",
"category": "Contract",
"q": "contract",
"sort": "largest",
"limit": 5,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"documents": [
{
"id": "d1",
"title": "Contract 2026",
"category": "Contract",
"subject": {
"kind": "person",
"person": {
"id": "p1",
"name": "Ana Ferreira"
}
},
"visibility": "hr_person",
"uploaded_by": "hr",
"field": null,
"expires_on": "2027-01-31",
"notes": "Signed copy",
"file": {
"name": "Contract 2026.pdf",
"size": 182000,
"content_type": "application/pdf",
"previewable": true
},
"access": "full",
"status": "ready",
"created_at": "2026-10-05T10:00:00.000Z",
"updated_at": "2026-10-05T10:00:00.000Z",
"signed_from": null,
"signature": {
"id": "sig_1",
"status": "ongoing",
"level": "advanced",
"signed": 1,
"total": 2,
"your_turn": false
}
},
{
"id": "d2",
"title": "Contract 2026",
"category": "Contract",
"subject": {
"kind": "person",
"person": {
"id": "p1",
"name": "Ana Ferreira"
}
},
"visibility": "hr_person",
"uploaded_by": "hr",
"field": null,
"expires_on": "2027-01-31",
"notes": null,
"file": {
"name": null,
"size": 182000,
"content_type": "application/pdf",
"previewable": true
},
"access": "metadata",
"status": "ready",
"created_at": "2026-10-05T10:00:00.000Z",
"updated_at": "2026-10-05T10:00:00.000Z",
"signed_from": null,
"signature": {
"id": "sig_1",
"status": "ongoing",
"level": "advanced",
"signed": 1,
"total": 2,
"your_turn": false
}
},
{
"id": "d3",
"title": "Employee handbook",
"category": "Handbook",
"subject": {
"kind": "company"
},
"visibility": "everyone",
"uploaded_by": "hr",
"field": null,
"expires_on": null,
"notes": null,
"file": {
"name": "Contract 2026.pdf",
"size": 182000,
"content_type": "application/pdf",
"previewable": true
},
"access": "full",
"status": "ready",
"created_at": "2026-10-05T10:00:00.000Z",
"updated_at": "2026-10-05T10:00:00.000Z",
"signed_from": null,
"signature": {
"id": "sig_1",
"status": "ongoing",
"level": "advanced",
"signed": 1,
"total": 2,
"your_turn": false
}
}
],
"categories": [
"Contract",
"Offer letter",
"Addendum",
"Payslip",
"Certificate",
"ID",
"Policy",
"Handbook",
"Other",
"Training"
],
"max_file_bytes": 25000000
}
}Start a document upload#
POST/v1/documents/upload.startWrite
Adds a document in two calls and one upload: (1) this call with the subject (a person, or the company), category, optional title (default: the file name), visibility, expires_on and notes, and the file's name, size, content_type and sha256; (2) PUT the file's bytes to the returned signed URL within 15 minutes, with exactly the returned headers (the size is part of them); (3) documents_upload_finish with the document id. Person document visibility: hr (owners, admins, HR), hr_person (default; also the person) or hr_person_manager (also their managers). Company: everyone (default), managers (people with reports and HR), hr, or accountant (HR and the company's accountants: an accounting firm with active access). Accepted: PDF, PNG, JPEG, WebP, HEIC, DOCX, XLSX, ODT, ODS, TXT, CSV (checked from the bytes; macros, archives and executables are refused); the largest file and the company's storage ceiling are set in Settings → Storage. Above 500 MB a company pays €1 per GB per month. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_upload_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
subjectobjectrequired3 fields (one of several shapes)
Option 1
kind"person"requiredperson_idstringrequired
Option 2
kind"company"required
categorystringrequired1–40 characters.
titlestringUp to 200 characters.
visibilitystring (enum)One of:
hr,hr_person,hr_person_manager,everyone,managers,hr,accountant.expires_onstring | nullPattern
^\d{4}-\d{2}-\d{2}$.notesstring | nullUp to 2000 characters.
notify_personbooleanA person document they can see (hr_person or hr_person_manager): tell them in Bizisy (and by email, per Settings → Notifications) once it is added. Default true; false adds it unannounced.
fileobjectrequired4 fields
namestringrequiredThe file name, e.g. "Contract 2026.pdf" (kept as metadata only).
1–500 characters.
sizeintegerrequiredBytes. Must equal what is uploaded.
At least 0.
content_typestringrequiredapplication/pdf, image/png, image/jpeg, image/webp, image/heic, DOCX, XLSX, ODT or ODS MIME type, text/plain or text/csv. Must match the bytes.
1–200 characters.
sha256stringrequiredLowercase hex SHA-256 of the file; checked against the upload.
Pattern
^[0-9a-f]{64}$.
Returns
documentobjectrequired19 fields
idstringrequiredtitlestringrequiredcategorystringrequiredsubjectobjectrequired3 fields (one of several shapes)
Option 1
kind"person"requiredpersonobject | nullrequired2 fields
idstringrequirednamestringrequired
Option 2
kind"company"required
visibilitystring (enum)requiredOne of:
hr,hr_person,hr_person_manager,everyone,managers,hr,accountant.uploaded_by"hr" | "self"requiredself: the person added it themself ("From me", or a custom field they fill in).
fieldobject | nullrequiredA custom file field's file (
org_fields_list): its visibility follows the field's tier; replace or remove it through the field.2 fields
keystringrequiredlabelstringrequired
expires_onstring | nullrequirednotesstring | nullrequirednull when you only see metadata.
fileobjectrequired4 fields
namestring | nullrequiredThe original file name; null when you only see metadata.
sizeintegerrequiredcontent_typestringrequiredpreviewablebooleanrequiredThe web app can show it (PDF, PNG, JPEG, WebP).
access"full" | "metadata"requiredmetadata: title, category, date and size only (no notes, no download): API keys and AI assistants never get the contents of other people's documents.
signed_fromobject | nullrequiredA signed copy or signature audit trail the e-signature tool handed back: the original document. null for other documents.
2 fields
document_idstringrequiredkind"signed" | "audit_trail"required
signatureobject | nullThe latest signature request (lists only): status, level and how many have signed.
6 fields
idstringrequiredstatusstring (enum)requiredOne of:
queued,sending,ongoing,done,declined,expired,canceled,failed.level"simple" | "advanced" | "qualified"requiredsignedintegerrequiredtotalintegerrequiredyour_turnbooleanrequiredYou are the signer the e-signature tool is waiting for (check your email from it).
generated_fromobject | nullMade from a document template: which one, its version, language and style (
documents_templates_get). null for uploaded documents.4 fields
template_idstringrequiredversionintegerrequiredlanguagestringrequiredstyle"international" | "continental"requiredThe document style it was made in (international or continental); null for documents made before styles existed.
draftobject | nullA draft only HR sees until it is sent (
documents_prepared_decide): the prepared document, and who will see it once sent. null otherwise.2 fields
prepared_idstringrequiredvisibility"hr" | "hr_person" | "hr_person_manager"required
deliveryobject | nullProof of delivery of a written statement or change notice: when it was sent, first opened and its receipt confirmed (or handed over on paper). null for other documents.
5 fields
method"electronic" | "print"requiredsent_atstringrequiredopened_atstring | nullrequiredacknowledged_atstring | nullrequiredhanded_over_onstring | nullrequired
status"pending" | "ready"requiredcreated_atstringrequiredupdated_atstringrequired
uploadobject | nullrequirednull on a dry run.
4 fields
urlstringrequiredShort-lived signed URL (15 minutes). Never share it.
method"PUT"requiredheadersobjectrequiredSend exactly these headers (they include the exact file size: any other size is refused).
resumablefalserequiredAlways false: upload the whole file in one PUT.
upload_expires_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/upload.start \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"subject": {
"kind": "person",
"person_id": "p1"
},
"category": "Contract",
"title": "Contract 2026",
"visibility": "hr_person_manager",
"expires_on": "2027-01-31",
"notes": "Signed",
"file": {
"name": "Contract 2026.pdf",
"size": 182000,
"content_type": "application/pdf",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
}'const res = await fetch('https://api.bizisy.com/v1/documents/upload.start', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"subject": {
"kind": "person",
"person_id": "p1"
},
"category": "Contract",
"title": "Contract 2026",
"visibility": "hr_person_manager",
"expires_on": "2027-01-31",
"notes": "Signed",
"file": {
"name": "Contract 2026.pdf",
"size": 182000,
"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/documents/upload.start",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"subject": {
"kind": "person",
"person_id": "p1",
},
"category": "Contract",
"title": "Contract 2026",
"visibility": "hr_person_manager",
"expires_on": "2027-01-31",
"notes": "Signed",
"file": {
"name": "Contract 2026.pdf",
"size": 182000,
"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": {
"document": {
"id": "d1",
"title": "Contract 2026",
"category": "Contract",
"subject": {
"kind": "person",
"person": {
"id": "p1",
"name": "Ana Ferreira"
}
},
"visibility": "hr_person",
"uploaded_by": "hr",
"field": null,
"expires_on": "2027-01-31",
"notes": "Signed copy",
"file": {
"name": "Contract 2026.pdf",
"size": 182000,
"content_type": "application/pdf",
"previewable": true
},
"access": "full",
"status": "pending",
"created_at": "2026-10-05T10:00:00.000Z",
"updated_at": "2026-10-05T10:00:00.000Z",
"signed_from": null,
"signature": {
"id": "sig_1",
"status": "ongoing",
"level": "advanced",
"signed": 1,
"total": 2,
"your_turn": false
}
},
"upload": {
"url": "https://storage.googleapis.com/b/uploads/o1/d1?X-Goog-Signature=x",
"method": "PUT",
"headers": {
"content-type": "application/pdf",
"x-goog-content-length-range": "182000,182000",
"x-goog-if-generation-match": "0"
},
"resumable": false
},
"upload_expires_at": "2026-10-05T10:15:00.000Z"
}
}Finish a document upload#
POST/v1/documents/upload.finishWrite
Finishes an upload started with documents_upload_start, after the bytes were uploaded: Bizisy checks the size, the SHA-256 and the type from the bytes, then the document appears for everyone its visibility allows. A file that does not match is deleted and refused (start again). Finishing twice returns the document. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_upload_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
document_idstringrequired
Returns
19 fields
idstringrequiredtitlestringrequiredcategorystringrequiredsubjectobjectrequired3 fields (one of several shapes)
Option 1
kind"person"requiredpersonobject | nullrequired2 fields
idstringrequirednamestringrequired
Option 2
kind"company"required
visibilitystring (enum)requiredOne of:
hr,hr_person,hr_person_manager,everyone,managers,hr,accountant.uploaded_by"hr" | "self"requiredself: the person added it themself ("From me", or a custom field they fill in).
fieldobject | nullrequiredA custom file field's file (
org_fields_list): its visibility follows the field's tier; replace or remove it through the field.2 fields
keystringrequiredlabelstringrequired
expires_onstring | nullrequirednotesstring | nullrequirednull when you only see metadata.
fileobjectrequired4 fields
namestring | nullrequiredThe original file name; null when you only see metadata.
sizeintegerrequiredcontent_typestringrequiredpreviewablebooleanrequiredThe web app can show it (PDF, PNG, JPEG, WebP).
access"full" | "metadata"requiredmetadata: title, category, date and size only (no notes, no download): API keys and AI assistants never get the contents of other people's documents.
signed_fromobject | nullrequiredA signed copy or signature audit trail the e-signature tool handed back: the original document. null for other documents.
2 fields
document_idstringrequiredkind"signed" | "audit_trail"required
signatureobject | nullThe latest signature request (lists only): status, level and how many have signed.
6 fields
idstringrequiredstatusstring (enum)requiredOne of:
queued,sending,ongoing,done,declined,expired,canceled,failed.level"simple" | "advanced" | "qualified"requiredsignedintegerrequiredtotalintegerrequiredyour_turnbooleanrequiredYou are the signer the e-signature tool is waiting for (check your email from it).
generated_fromobject | nullMade from a document template: which one, its version, language and style (
documents_templates_get). null for uploaded documents.4 fields
template_idstringrequiredversionintegerrequiredlanguagestringrequiredstyle"international" | "continental"requiredThe document style it was made in (international or continental); null for documents made before styles existed.
draftobject | nullA draft only HR sees until it is sent (
documents_prepared_decide): the prepared document, and who will see it once sent. null otherwise.2 fields
prepared_idstringrequiredvisibility"hr" | "hr_person" | "hr_person_manager"required
deliveryobject | nullProof of delivery of a written statement or change notice: when it was sent, first opened and its receipt confirmed (or handed over on paper). null for other documents.
5 fields
method"electronic" | "print"requiredsent_atstringrequiredopened_atstring | nullrequiredacknowledged_atstring | nullrequiredhanded_over_onstring | nullrequired
status"pending" | "ready"requiredcreated_atstringrequiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/upload.finish \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"document_id":"d1"}'const res = await fetch('https://api.bizisy.com/v1/documents/upload.finish', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"document_id": "d1"
}),
});
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/documents/upload.finish",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"document_id": "d1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "d1",
"title": "Contract 2026",
"category": "Contract",
"subject": {
"kind": "person",
"person": {
"id": "p1",
"name": "Ana Ferreira"
}
},
"visibility": "hr_person",
"uploaded_by": "hr",
"field": null,
"expires_on": "2027-01-31",
"notes": "Signed copy",
"file": {
"name": "Contract 2026.pdf",
"size": 182000,
"content_type": "application/pdf",
"previewable": true
},
"access": "full",
"status": "ready",
"created_at": "2026-10-05T10:00:00.000Z",
"updated_at": "2026-10-05T10:00:00.000Z",
"signed_from": null,
"signature": {
"id": "sig_1",
"status": "ongoing",
"level": "advanced",
"signed": 1,
"total": 2,
"your_turn": false
}
}
}Change a document#
POST/v1/documents/updateWrite
Changes a document's title, category, visibility, expiry date (expires_on, YYYY-MM-DD or null) or notes. Send only what changes. The visibility of a person's own "From me" upload stays hr_person; a custom field's file (field set) keeps the field's visibility and category (change the field instead). Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_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
document_idstringrequiredtitlestring1–200 characters.
categorystring1–40 characters.
visibilitystring (enum)One of:
hr,hr_person,hr_person_manager,everyone,managers,hr,accountant.expires_onstring | nullPattern
^\d{4}-\d{2}-\d{2}$.notesstring | nullUp to 2000 characters.
notify_personbooleanWhen this change lets the person see a document they could not (visibility from hr to hr_person or hr_person_manager): tell them (default true).
Returns
19 fields
idstringrequiredtitlestringrequiredcategorystringrequiredsubjectobjectrequired3 fields (one of several shapes)
Option 1
kind"person"requiredpersonobject | nullrequired2 fields
idstringrequirednamestringrequired
Option 2
kind"company"required
visibilitystring (enum)requiredOne of:
hr,hr_person,hr_person_manager,everyone,managers,hr,accountant.uploaded_by"hr" | "self"requiredself: the person added it themself ("From me", or a custom field they fill in).
fieldobject | nullrequiredA custom file field's file (
org_fields_list): its visibility follows the field's tier; replace or remove it through the field.2 fields
keystringrequiredlabelstringrequired
expires_onstring | nullrequirednotesstring | nullrequirednull when you only see metadata.
fileobjectrequired4 fields
namestring | nullrequiredThe original file name; null when you only see metadata.
sizeintegerrequiredcontent_typestringrequiredpreviewablebooleanrequiredThe web app can show it (PDF, PNG, JPEG, WebP).
access"full" | "metadata"requiredmetadata: title, category, date and size only (no notes, no download): API keys and AI assistants never get the contents of other people's documents.
signed_fromobject | nullrequiredA signed copy or signature audit trail the e-signature tool handed back: the original document. null for other documents.
2 fields
document_idstringrequiredkind"signed" | "audit_trail"required
signatureobject | nullThe latest signature request (lists only): status, level and how many have signed.
6 fields
idstringrequiredstatusstring (enum)requiredOne of:
queued,sending,ongoing,done,declined,expired,canceled,failed.level"simple" | "advanced" | "qualified"requiredsignedintegerrequiredtotalintegerrequiredyour_turnbooleanrequiredYou are the signer the e-signature tool is waiting for (check your email from it).
generated_fromobject | nullMade from a document template: which one, its version, language and style (
documents_templates_get). null for uploaded documents.4 fields
template_idstringrequiredversionintegerrequiredlanguagestringrequiredstyle"international" | "continental"requiredThe document style it was made in (international or continental); null for documents made before styles existed.
draftobject | nullA draft only HR sees until it is sent (
documents_prepared_decide): the prepared document, and who will see it once sent. null otherwise.2 fields
prepared_idstringrequiredvisibility"hr" | "hr_person" | "hr_person_manager"required
deliveryobject | nullProof of delivery of a written statement or change notice: when it was sent, first opened and its receipt confirmed (or handed over on paper). null for other documents.
5 fields
method"electronic" | "print"requiredsent_atstringrequiredopened_atstring | nullrequiredacknowledged_atstring | nullrequiredhanded_over_onstring | nullrequired
status"pending" | "ready"requiredcreated_atstringrequiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"document_id": "d1",
"category": "Addendum",
"visibility": "hr",
"expires_on": null,
"notes": null
}'const res = await fetch('https://api.bizisy.com/v1/documents/update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"document_id": "d1",
"category": "Addendum",
"visibility": "hr",
"expires_on": null,
"notes": null
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/documents/update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"document_id": "d1",
"category": "Addendum",
"visibility": "hr",
"expires_on": None,
"notes": None,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "d1",
"title": "Contract 2026",
"category": "Addendum",
"subject": {
"kind": "person",
"person": {
"id": "p1",
"name": "Ana Ferreira"
}
},
"visibility": "hr",
"uploaded_by": "hr",
"field": null,
"expires_on": null,
"notes": null,
"file": {
"name": "Contract 2026.pdf",
"size": 182000,
"content_type": "application/pdf",
"previewable": true
},
"access": "full",
"status": "ready",
"created_at": "2026-10-05T10:00:00.000Z",
"updated_at": "2026-10-05T10:00:00.000Z",
"signed_from": null,
"signature": {
"id": "sig_1",
"status": "ongoing",
"level": "advanced",
"signed": 1,
"total": 2,
"your_turn": false
}
}
}Delete a document#
POST/v1/documents/deleteDestructive
Deletes a document and its file for good (no recycle bin; the storage it used is freed, though this month's billed peak does not go down). A custom field's file (field set) is removed from the field too. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_deleteon 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
document_idstringrequired
Returns
idstringrequireddeletedtruerequiredcategorystringrequiredperson_idstring | nullrequiredvisibilitystringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/delete \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"document_id":"d1"}'const res = await fetch('https://api.bizisy.com/v1/documents/delete', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"document_id": "d1"
}),
});
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/documents/delete",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"document_id": "d1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "d1",
"deleted": true,
"category": "Contract",
"person_id": "p1",
"visibility": "hr_person"
}
}Download a document#
POST/v1/documents/downloadWrite
Returns a short-lived link (5 minutes) that downloads the document as a file. Downloading a person's document is recorded in Activity (company documents are not). Only for documents you can fully see: through an API key or an AI assistant, other people's documents never download. The link is never stored; ask again for a new one.
- Who can call it
- Manage key any Manage role
- Keys and apps
- Other people's documents never download.
- MCP tool
documents_downloadon 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
document_idstringrequired
Returns
8 fields
urlstring | nullrequiredSigned URL valid for 5 minutes, downloads as an attachment. null on a dry run. Never store or share it.
expires_atstring | nullrequiredfile_namestringrequiredcontent_typestringrequiredsizeintegerrequiredcategorystringrequiredperson_idstring | nullrequiredvisibilitystringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/download \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"document_id":"d1"}'const res = await fetch('https://api.bizisy.com/v1/documents/download', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"document_id": "d1"
}),
});
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/documents/download",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"document_id": "d1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"url": "https://storage.googleapis.com/b/orgs/o1/files/d1?X-Goog-Signature=x",
"expires_at": "2026-10-05T10:05:00.000Z",
"file_name": "Contract 2026.pdf",
"content_type": "application/pdf",
"size": 182000,
"category": "Contract",
"person_id": "p1",
"visibility": "hr_person"
}
}See document categories#
POST/v1/documents/categories.getRead
The document categories: the starter list (Contract, Addendum, Certificate, ID, Policy, Handbook, Other) and your own.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
documents_categories_geton HR Assistant, My Workplace- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
starterstring[]requiredcustomstring[]required
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/categories.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/documents/categories.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/documents/categories.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": {
"starter": [
"Contract",
"Offer letter",
"Addendum",
"Payslip",
"Certificate",
"ID",
"Policy",
"Handbook",
"Other"
],
"custom": [
"Training"
]
}
}Change document categories#
POST/v1/documents/categories.setWrite
Replaces your own document categories (up to 30, each up to 40 characters) beside the starter list. Documents keep the category they have when one is removed. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_categories_seton HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
customstring[]required1–40 characters. Up to 30 items.
Returns
starterstring[]requiredcustomstring[]required
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/categories.set \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"custom":["Training","Medical note"]}'const res = await fetch('https://api.bizisy.com/v1/documents/categories.set', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"custom": [
"Training",
"Medical note"
]
}),
});
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/documents/categories.set",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"custom": [
"Training",
"Medical note",
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"starter": [
"Contract",
"Offer letter",
"Addendum",
"Payslip",
"Certificate",
"ID",
"Policy",
"Handbook",
"Other"
],
"custom": [
"Training"
]
}
}Ask a person for a document#
POST/v1/documents/requests.createWrite
Asks a person to add a document of a category (documents_categories_get), e.g. a new ID card, optionally by due_on (YYYY-MM-DD) with a short note to them. They see it in My workspace → My documents and get an in-app notice (no email); they can add it there when your company lets people add their own documents, otherwise you add it for them. It closes by itself when a document of that category is added for them (their own upload or yours), or with documents_requests_cancel. One open request per person and category; at most 20 open per person. Owners, admins and HR, or a role with Documents at Edit covering the person.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_requests_createon 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_idstringrequiredcategorystringrequired1–40 characters.
due_onstring | nullPattern
^\d{4}-\d{2}-\d{2}$.notestring | nullUp to 300 characters.
Returns
11 fields
idstringrequiredpersonobject | nullrequired2 fields
idstringrequirednamestringrequired
categorystringrequirednotestring | nullrequireddue_onstring | nullrequiredstatus"open" | "fulfilled" | "cancelled"requiredoverduebooleanrequiredOpen and past due_on.
created_atstringrequiredfulfilled_atstring | nullrequiredfulfilled_document_idstring | nullrequiredcancelled_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/requests.create \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"person_id": "p1",
"category": "ID",
"due_on": "2026-10-31",
"note": "The new card, both sides"
}'const res = await fetch('https://api.bizisy.com/v1/documents/requests.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_id": "p1",
"category": "ID",
"due_on": "2026-10-31",
"note": "The new card, both sides"
}),
});
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/documents/requests.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p1",
"category": "ID",
"due_on": "2026-10-31",
"note": "The new card, both sides",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "dr1",
"person": {
"id": "p1",
"name": "Ana Ferreira"
},
"category": "ID",
"note": "The new card, both sides",
"due_on": "2026-10-31",
"status": "open",
"overdue": false,
"created_at": "2026-10-05T10:00:00.000Z",
"fulfilled_at": null,
"fulfilled_document_id": null,
"cancelled_at": null
}
}List document requests#
POST/v1/documents/requests.listRead
Document requests, newest first: status open (default), fulfilled, cancelled or all; person_id: only theirs. Each says the category, the note, due_on and overdue, and the document that fulfilled it. Owners, admins and HR see everyone's; a role with Documents at Edit sees those of the people it covers.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_requests_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
person_idstringstatus"open" | "fulfilled" | "cancelled" | "all"Default
"open".
Returns
requestsobject[]required11 fields
idstringrequiredpersonobject | nullrequired2 fields
idstringrequirednamestringrequired
categorystringrequirednotestring | nullrequireddue_onstring | nullrequiredstatus"open" | "fulfilled" | "cancelled"requiredoverduebooleanrequiredOpen and past due_on.
created_atstringrequiredfulfilled_atstring | nullrequiredfulfilled_document_idstring | nullrequiredcancelled_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/requests.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"person_id":"p1","status":"all"}'const res = await fetch('https://api.bizisy.com/v1/documents/requests.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"person_id": "p1",
"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/documents/requests.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"person_id": "p1",
"status": "all",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"requests": [
{
"id": "dr1",
"person": {
"id": "p1",
"name": "Ana Ferreira"
},
"category": "ID",
"note": "The new card, both sides",
"due_on": "2026-10-31",
"status": "open",
"overdue": false,
"created_at": "2026-10-05T10:00:00.000Z",
"fulfilled_at": null,
"fulfilled_document_id": null,
"cancelled_at": null
}
]
}
}Cancel a document request#
POST/v1/documents/requests.cancelWrite
Cancels an open document request (it no longer shows in the person's My documents). Owners, admins and HR, or a role with Documents at Edit covering the person.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_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
request_idstringrequired
Returns
11 fields
idstringrequiredpersonobject | nullrequired2 fields
idstringrequirednamestringrequired
categorystringrequirednotestring | nullrequireddue_onstring | nullrequiredstatus"open" | "fulfilled" | "cancelled"requiredoverduebooleanrequiredOpen and past due_on.
created_atstringrequiredfulfilled_atstring | nullrequiredfulfilled_document_idstring | nullrequiredcancelled_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/requests.cancel \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"request_id":"dr1"}'const res = await fetch('https://api.bizisy.com/v1/documents/requests.cancel', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"request_id": "dr1"
}),
});
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/documents/requests.cancel",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"request_id": "dr1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "dr1",
"person": {
"id": "p1",
"name": "Ana Ferreira"
},
"category": "ID",
"note": "The new card, both sides",
"due_on": "2026-10-31",
"status": "cancelled",
"overdue": false,
"created_at": "2026-10-05T10:00:00.000Z",
"fulfilled_at": null,
"fulfilled_document_id": null,
"cancelled_at": "2026-10-06T09:00:00.000Z"
}
}List document templates#
POST/v1/documents/templates.listRead
Lists document templates: Bizisy's built-ins (source builtin, ready to use; copy one to change it) and your company's own (drafts and published; archived ones with status archived or all). Each: kind (contract_open, contract_fixed, contract_part_time, statement, amendment, change_notice, end_notice, certificate, declaration, policy, letter), name, category, countries, languages, signers, who sees the generated documents, status, latest version, tier (the most sensitive fields it uses: public, job, private, pay) and, for built-ins, whether a lawyer reviewed the text. Filters: kind, country (templates for it or for every country), status. Owners, admins and HR (and custom roles with Documents at Edit). Bodies come from documents_templates_get.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_templates_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
kindstring (enum)One of:
contract_open,contract_fixed,contract_part_time,statement,amendment,change_notice,end_notice,certificate,declaration,policy,letter,offer_letter,pay_review_letter.countrystringPattern
^[A-Z]{2}$.status"draft" | "published" | "archived" | "all"Default: drafts and published (not archived).
source"builtin" | "company"
Returns
templatesobject[]required20 fields
idstringrequiredA company template's id, or a built-in's (builtin:…).
source"builtin" | "company"requiredbuiltin: Bizisy's (copy it to change it); company: your own.
kindstring (enum)requiredcontract_open, contract_fixed, contract_part_time, statement, amendment, change_notice, end_notice, certificate, declaration, policy, letter, offer_letter (Hiring's offer letter: its fields only), or pay_review_letter (Salary reviews' letter: the review's fields review.* with the person's, sent at release).
One of:
contract_open,contract_fixed,contract_part_time,statement,amendment,change_notice,end_notice,certificate,declaration,policy,letter,offer_letter,pay_review_letter.namestringrequiredcategorystringrequiredThe Documents category the generated documents get.
countriesstring[]requiredThe countries it is for (* = every country).
languages"en" | "pt" | "es" | "fr" | "de" | "it"[]requiredsignersobject[]requiredWho signs, in order: employer, person, manager, or a named person.
5 fields (one of several shapes)
Option 1
role"employer"required
Option 2
role"person"required
Option 3
role"manager"required
Option 4
role"named"requiredperson_idstringrequired
visibility"hr" | "hr_person" | "hr_person_manager"requiredWho sees the generated documents: hr, hr_person (default) or hr_person_manager.
status"draft" | "published" | "archived"requiredversionintegerrequiredThe latest published version (0: never published).
has_draftbooleanrequiredThe draft has changes not published yet.
tier"public" | "job" | "private" | "pay"requiredThe most sensitive fields it uses: public, job, private or pay. Pay templates are for those who see pay; private and pay ones are generated in the web app only.
reviewedboolean | nullrequiredBuilt-ins: a local employment lawyer reviewed the text (false: not yet). null for your own.
builtin_fromstring | nullrequiredThe template it was copied from.
updated_atstring | nullrequiredslotsobject[]requiredClause slots ({{#clauses "name"}}): the clause types HR may pick there when generating, and the ones ticked by default.
3 fields
namestringrequiredallowedstring (enum)[]requiredOne of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months.defaultsstring (enum)[]requiredOne of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months.
letter_kind"permanent" | "fixed_term"requiredOffer letters: the contract kind Hiring uses it for (permanent; fixed_term, also temporary and internship contracts). null for other kinds.
approvalobject | nullrequiredA version waiting for approval, or sent back with a comment (when your company requires approval to publish).
7 fields
state"pending" | "rejected"requiredpending: waits for an approver; rejected: sent back (the draft is unchanged: change it and publish again).
approvers"hr" | "owner"requiredhr: an owner, admin or HR member; owner: an owner. Never whoever asked or changed the draft last.
versionintegerrequiredThe version it makes once approved.
asked_atstringrequiredasked_by_youbooleanrequiredcan_decidebooleanrequiredYou may approve it or send it back (signed in to Bizisy, an approver by the rule, not its asker or last editor).
decidedobject | nullrequiredWhen it was sent back, with the approver's comment.
2 fields
atstringrequiredcommentstring | nullrequired
style"international" | "continental"requiredThe default document style of what it makes: international (1. / 1.1 / (a)) or continental (Cláusula 1.ª / 1 – / a)). null: the company's default, else the country's. A style chosen when generating wins.
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/templates.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"kind": "contract_fixed",
"country": "PT",
"status": "all",
"source": "company"
}'const res = await fetch('https://api.bizisy.com/v1/documents/templates.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"kind": "contract_fixed",
"country": "PT",
"status": "all",
"source": "company"
}),
});
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/documents/templates.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"kind": "contract_fixed",
"country": "PT",
"status": "all",
"source": "company",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"templates": [
{
"id": "builtin:letter-all-employment",
"source": "builtin",
"kind": "letter",
"name": "Employment confirmation letter",
"category": "Other",
"countries": [
"*"
],
"languages": [
"en",
"pt",
"es",
"fr",
"de",
"it"
],
"signers": [
{
"role": "employer"
}
],
"visibility": "hr_person",
"status": "published",
"version": 1,
"has_draft": false,
"tier": "job",
"reviewed": false,
"builtin_from": null,
"updated_at": null,
"slots": [],
"letter_kind": null,
"approval": null,
"style": null
},
{
"id": "tpl1",
"source": "company",
"kind": "contract_fixed",
"name": "Fixed-term contract (PT)",
"category": "Contract",
"countries": [
"PT"
],
"languages": [
"pt",
"en"
],
"signers": [
{
"role": "employer"
},
{
"role": "person"
}
],
"visibility": "hr_person",
"status": "published",
"version": 2,
"has_draft": true,
"tier": "pay",
"reviewed": null,
"builtin_from": "builtin:letter-all-employment",
"updated_at": "2026-10-19T10:00:00.000Z",
"slots": [
{
"name": "optional",
"allowed": [
"confidentiality",
"non_compete"
],
"defaults": [
"confidentiality"
]
}
],
"letter_kind": null,
"approval": {
"state": "pending",
"approvers": "hr",
"version": 3,
"asked_at": "2026-10-19T11:00:00.000Z",
"asked_by_you": true,
"can_decide": false,
"decided": null
},
"style": "continental"
}
]
}
}Get a document template#
POST/v1/documents/templates.getRead
One template (a built-in or your own) with its bodies per language (the draft for your own), published versions, the fields it uses, lint warnings and the law panel per country it is for: which items the law asks the document to contain (covered, missing, optional, to check by hand), the minimum signature level, the delivery deadline and the language. A template with pay details shows its body only to those who see pay (never to API keys or AI assistants). The law panel is a starting point, not legal advice.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Templates with pay details come without their text.
- MCP tool
documents_templates_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
template_idstringrequired
Returns
26 fields
idstringrequiredA company template's id, or a built-in's (builtin:…).
source"builtin" | "company"requiredbuiltin: Bizisy's (copy it to change it); company: your own.
kindstring (enum)requiredcontract_open, contract_fixed, contract_part_time, statement, amendment, change_notice, end_notice, certificate, declaration, policy, letter, offer_letter (Hiring's offer letter: its fields only), or pay_review_letter (Salary reviews' letter: the review's fields review.* with the person's, sent at release).
One of:
contract_open,contract_fixed,contract_part_time,statement,amendment,change_notice,end_notice,certificate,declaration,policy,letter,offer_letter,pay_review_letter.namestringrequiredcategorystringrequiredThe Documents category the generated documents get.
countriesstring[]requiredThe countries it is for (* = every country).
languages"en" | "pt" | "es" | "fr" | "de" | "it"[]requiredsignersobject[]requiredWho signs, in order: employer, person, manager, or a named person.
5 fields (one of several shapes)
Option 1
role"employer"required
Option 2
role"person"required
Option 3
role"manager"required
Option 4
role"named"requiredperson_idstringrequired
visibility"hr" | "hr_person" | "hr_person_manager"requiredWho sees the generated documents: hr, hr_person (default) or hr_person_manager.
status"draft" | "published" | "archived"requiredversionintegerrequiredThe latest published version (0: never published).
has_draftbooleanrequiredThe draft has changes not published yet.
tier"public" | "job" | "private" | "pay"requiredThe most sensitive fields it uses: public, job, private or pay. Pay templates are for those who see pay; private and pay ones are generated in the web app only.
reviewedboolean | nullrequiredBuilt-ins: a local employment lawyer reviewed the text (false: not yet). null for your own.
builtin_fromstring | nullrequiredThe template it was copied from.
updated_atstring | nullrequiredslotsobject[]requiredClause slots ({{#clauses "name"}}): the clause types HR may pick there when generating, and the ones ticked by default.
3 fields
namestringrequiredallowedstring (enum)[]requiredOne of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months.defaultsstring (enum)[]requiredOne of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months.
letter_kind"permanent" | "fixed_term"requiredOffer letters: the contract kind Hiring uses it for (permanent; fixed_term, also temporary and internship contracts). null for other kinds.
approvalobject | nullrequiredA version waiting for approval, or sent back with a comment (when your company requires approval to publish).
7 fields
state"pending" | "rejected"requiredpending: waits for an approver; rejected: sent back (the draft is unchanged: change it and publish again).
approvers"hr" | "owner"requiredhr: an owner, admin or HR member; owner: an owner. Never whoever asked or changed the draft last.
versionintegerrequiredThe version it makes once approved.
asked_atstringrequiredasked_by_youbooleanrequiredcan_decidebooleanrequiredYou may approve it or send it back (signed in to Bizisy, an approver by the rule, not its asker or last editor).
decidedobject | nullrequiredWhen it was sent back, with the approver's comment.
2 fields
atstringrequiredcommentstring | nullrequired
style"international" | "continental"requiredThe default document style of what it makes: international (1. / 1.1 / (a)) or continental (Cláusula 1.ª / 1 – / a)). null: the company's default, else the country's. A style chosen when generating wins.
bodiesobject | nullrequiredEach language's title and body; null when the template uses pay details and you can't see pay.
6 fields
enobject2 fields
titlestringrequiredbodystringrequired
ptobject2 fields
titlestringrequiredbodystringrequired
esobject2 fields
titlestringrequiredbodystringrequired
frobject2 fields
titlestringrequiredbodystringrequired
deobject2 fields
titlestringrequiredbodystringrequired
itobject2 fields
titlestringrequiredbodystringrequired
body_hiddenbooleanrequiredversionsobject[]requiredPublished versions, newest first (built-ins: none listed).
3 fields
versionintegerrequiredpublished_atstringrequiredtier"public" | "job" | "private" | "pay"required
problemsobject[]requiredWarnings in the draft (errors are refused when saving).
8 fields
language"en" | "pt" | "es" | "fr" | "de" | "it"requiredfield"title" | "body"requiredlineintegerrequiredcolintegerrequiredcodestringrequiredmessagestringrequiredEnglish; the app translates by code.
severity"error" | "warning"requiredparamsobject
fieldsstring[]requiredThe fields the template uses.
lawobject[]requiredPer country it is for (EU: the Directive minimum when it is for every country).
11 fields
countrystringrequiredThe country whose rules apply (EU: Directive 2019/1152, for any other country).
reviewedbooleanrequiredA local employment lawyer checked this country's rules.
coveredobject[]required6 fields
idstringrequiredlabelstringrequiredEnglish; the app translates it.
requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requirednotestring | nullrequired
missingobject[]requiredRequired items the template does not cover.
6 fields
idstringrequiredlabelstringrequiredEnglish; the app translates it.
requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requirednotestring | nullrequired
optionalobject[]requiredItems needed only sometimes (fixed-term, probation…) that it does not cover.
6 fields
idstringrequiredlabelstringrequiredEnglish; the app translates it.
requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requirednotestring | nullrequired
manualobject[]requiredItems Bizisy cannot check by field: make sure the text says them.
6 fields
idstringrequiredlabelstringrequiredEnglish; the app translates it.
requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requirednotestring | nullrequired
signatureobjectrequired6 fields
min_level"none" | "simple" | "advanced" | "qualified" | "wet"requiredThe lowest signature level that makes it valid (wet: printed and signed by hand).
whostring[]requirednotestringrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requiredOnly verified rules block; others warn.
alternativesstring[]required
deliveryobjectrequired3 fields
deadlinestringrequiredbefore_start, on_start, days_after_start, by_effective_date, before_end, on_last_day, on_request or none.
proof_requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
languageobjectrequired3 fields
mandatorystring | nullrequireddefaultstring | nullrequiredtranslation_allowedbooleanrequired
dueobject[]requiredFor a person: by when each part must reach them.
2 fields
partstringrequiredduestringrequired
disclaimerstringrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/templates.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"template_id":"tpl1"}'const res = await fetch('https://api.bizisy.com/v1/documents/templates.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"template_id": "tpl1"
}),
});
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/documents/templates.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"template_id": "tpl1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "tpl1",
"source": "company",
"kind": "contract_fixed",
"name": "Fixed-term contract (PT)",
"category": "Contract",
"countries": [
"PT"
],
"languages": [
"pt",
"en"
],
"signers": [
{
"role": "employer"
},
{
"role": "person"
}
],
"visibility": "hr_person",
"status": "published",
"version": 2,
"has_draft": true,
"tier": "pay",
"reviewed": null,
"builtin_from": "builtin:letter-all-employment",
"updated_at": "2026-10-19T10:00:00.000Z",
"slots": [
{
"name": "optional",
"allowed": [
"confidentiality",
"non_compete"
],
"defaults": [
"confidentiality"
]
}
],
"letter_kind": null,
"approval": {
"state": "pending",
"approvers": "hr",
"version": 3,
"asked_at": "2026-10-19T11:00:00.000Z",
"asked_by_you": true,
"can_decide": false,
"decided": null
},
"style": "continental",
"bodies": {
"pt": {
"title": "Contrato a termo – {{person.full_name}}",
"body": "# Contrato de trabalho a termo certo\n\n{{employer.legal_name}} e {{person.full_name}}…\n\n{{signature.employer}}\n\n{{signature.person}}\n"
}
},
"body_hidden": false,
"versions": [
{
"version": 2,
"published_at": "2026-10-19T10:00:00.000Z",
"tier": "pay"
},
{
"version": 1,
"published_at": "2026-10-18T10:00:00.000Z",
"tier": "pay"
}
],
"problems": [
{
"language": "pt",
"field": "body",
"line": 3,
"col": 1,
"code": "long_word",
"message": "\"…\" is too long for a line; it will be cut where the page ends.",
"severity": "warning",
"params": {
"word": "x"
}
}
],
"fields": [
"employer.legal_name",
"person.full_name"
],
"law": [
{
"country": "PT",
"reviewed": false,
"covered": [
{
"id": "parties.person",
"label": "The employee's identity",
"required": true,
"source": {
"url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
"article": "Código do Trabalho, art. 141"
},
"confidence": "verified",
"note": null
}
],
"missing": [
{
"id": "reason_for_term",
"label": "The reason for the fixed term",
"required": true,
"source": {
"url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
"article": "Código do Trabalho, art. 141"
},
"confidence": "verified",
"note": "Name the specific facts that justify the term."
}
],
"optional": [],
"manual": [],
"signature": {
"min_level": "qualified",
"who": [
"employer",
"person"
],
"note": "Written form: both sign with a qualified electronic signature or print and sign by hand.",
"source": {
"url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
"article": "Código do Trabalho, art. 141"
},
"confidence": "verified",
"alternatives": [
"print"
]
},
"delivery": {
"deadline": "days_after_start",
"proof_required": true,
"source": {
"url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
"article": "Código do Trabalho, art. 141"
}
},
"language": {
"mandatory": null,
"default": "pt",
"translation_allowed": true
},
"due": [
{
"part": "all",
"due": "2026-11-09"
}
],
"disclaimer": "Bizisy checks the legal minimum it knows of. It is a starting point, not legal advice: have your templates checked."
}
]
}
}Create a document template#
POST/v1/documents/templates.createWrite
Creates a draft template of your company: kind, name, category (a Documents category: what the generated documents are filed as), countries (2-letter codes, or ["*"] for every country), bodies per language (en, pt, es, fr, de, it: { title, body }), signers in order (employer, person, manager, named with person_id; up to 5) and visibility of the generated documents (hr, hr_person (default), hr_person_manager). Body syntax: Markdown-lite (# heading, - list, 1. list, | table |, --- page break, **bold**, *italic*), {{field}} placeholders (documents_templates_get on a built-in shows them in use; unknown fields are refused with a suggestion), {{#if job.contract is fixed_term}}…{{else}}…{{/if}} (is, is not, is empty, is set, >, <, before, after; and/or), {{#each pay.components}}{{this.name}}{{/each}}, and {{signature.employer}} / {{signature.person}} / {{signature.manager}} on lines of their own. Titles may use public fields only. Lint errors refuse the save and list each problem (language, line, column). style (optional): the template's default document style, international or continental; leave it out (null) to use the company's default, else the country's. Publish it (documents_templates_publish) to generate documents from it. At most 300 templates. Owners, admins and HR; API keys and AI assistants may draft templates without pay details.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- No templates with pay details.
- MCP tool
documents_templates_createon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
kindstring (enum)requiredOne of:
contract_open,contract_fixed,contract_part_time,statement,amendment,change_notice,end_notice,certificate,declaration,policy,letter,offer_letter,pay_review_letter.namestringrequired1–120 characters.
categorystringrequired1–40 characters.
countriesstring[]Default ["*"]: every country.
1–30 items. Pattern
^([A-Z]{2}|\*)$.bodiesobjectrequired6 fields
enobject2 fields
titlestringrequiredThe generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".
1–200 characters.
bodystringrequiredThe template: Markdown-lite (# headings, - lists, | tables |, --- page break, **bold**, *italic*) with {{placeholders}}, {{#if path is value}}…{{else}}…{{/if}}, {{#each list}}…{{/each}} and {{signature.<role>}} blocks.
Up to 60000 characters.
ptobject2 fields
titlestringrequiredThe generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".
1–200 characters.
bodystringrequiredThe template: Markdown-lite (# headings, - lists, | tables |, --- page break, **bold**, *italic*) with {{placeholders}}, {{#if path is value}}…{{else}}…{{/if}}, {{#each list}}…{{/each}} and {{signature.<role>}} blocks.
Up to 60000 characters.
esobject2 fields
titlestringrequiredThe generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".
1–200 characters.
bodystringrequiredThe template: Markdown-lite (# headings, - lists, | tables |, --- page break, **bold**, *italic*) with {{placeholders}}, {{#if path is value}}…{{else}}…{{/if}}, {{#each list}}…{{/each}} and {{signature.<role>}} blocks.
Up to 60000 characters.
frobject2 fields
titlestringrequiredThe generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".
1–200 characters.
bodystringrequiredThe template: Markdown-lite (# headings, - lists, | tables |, --- page break, **bold**, *italic*) with {{placeholders}}, {{#if path is value}}…{{else}}…{{/if}}, {{#each list}}…{{/each}} and {{signature.<role>}} blocks.
Up to 60000 characters.
deobject2 fields
titlestringrequiredThe generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".
1–200 characters.
bodystringrequiredThe template: Markdown-lite (# headings, - lists, | tables |, --- page break, **bold**, *italic*) with {{placeholders}}, {{#if path is value}}…{{else}}…{{/if}}, {{#each list}}…{{/each}} and {{signature.<role>}} blocks.
Up to 60000 characters.
itobject2 fields
titlestringrequiredThe generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".
1–200 characters.
bodystringrequiredThe template: Markdown-lite (# headings, - lists, | tables |, --- page break, **bold**, *italic*) with {{placeholders}}, {{#if path is value}}…{{else}}…{{/if}}, {{#each list}}…{{/each}} and {{signature.<role>}} blocks.
Up to 60000 characters.
signersobject[]Default: the employer, then the person.
Up to 5 items.
5 fields (one of several shapes)
Option 1
role"employer"required
Option 2
role"person"required
Option 3
role"manager"required
Option 4
role"named"requiredperson_idstringrequired
visibility"hr" | "hr_person" | "hr_person_manager"slotsobject[]Settings of the clause slots its text uses ({{#clauses "name"}}): allowed clause types and the ones ticked by default.
Up to 10 items.
3 fields
namestringrequired1–40 characters. Pattern
^[a-z][a-z0-9_]*$.allowedstring (enum)[]requiredThe clause types HR may tick in this slot.
One of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months. 1–16 items.defaultsstring (enum)[]requiredTicked by default, in order (each must be allowed).
One of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months. Up to 16 items.
letter_kind"permanent" | "fixed_term"Offer letters only (kind offer_letter, required there): the contract kind Hiring sends it for: permanent, or fixed_term (also temporary and internship). One per kind.
style"international" | "continental"The default document style of what it makes (international or continental); null or absent: the company's default, else the country's.
Returns
26 fields
idstringrequiredA company template's id, or a built-in's (builtin:…).
source"builtin" | "company"requiredbuiltin: Bizisy's (copy it to change it); company: your own.
kindstring (enum)requiredcontract_open, contract_fixed, contract_part_time, statement, amendment, change_notice, end_notice, certificate, declaration, policy, letter, offer_letter (Hiring's offer letter: its fields only), or pay_review_letter (Salary reviews' letter: the review's fields review.* with the person's, sent at release).
One of:
contract_open,contract_fixed,contract_part_time,statement,amendment,change_notice,end_notice,certificate,declaration,policy,letter,offer_letter,pay_review_letter.namestringrequiredcategorystringrequiredThe Documents category the generated documents get.
countriesstring[]requiredThe countries it is for (* = every country).
languages"en" | "pt" | "es" | "fr" | "de" | "it"[]requiredsignersobject[]requiredWho signs, in order: employer, person, manager, or a named person.
5 fields (one of several shapes)
Option 1
role"employer"required
Option 2
role"person"required
Option 3
role"manager"required
Option 4
role"named"requiredperson_idstringrequired
visibility"hr" | "hr_person" | "hr_person_manager"requiredWho sees the generated documents: hr, hr_person (default) or hr_person_manager.
status"draft" | "published" | "archived"requiredversionintegerrequiredThe latest published version (0: never published).
has_draftbooleanrequiredThe draft has changes not published yet.
tier"public" | "job" | "private" | "pay"requiredThe most sensitive fields it uses: public, job, private or pay. Pay templates are for those who see pay; private and pay ones are generated in the web app only.
reviewedboolean | nullrequiredBuilt-ins: a local employment lawyer reviewed the text (false: not yet). null for your own.
builtin_fromstring | nullrequiredThe template it was copied from.
updated_atstring | nullrequiredslotsobject[]requiredClause slots ({{#clauses "name"}}): the clause types HR may pick there when generating, and the ones ticked by default.
3 fields
namestringrequiredallowedstring (enum)[]requiredOne of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months.defaultsstring (enum)[]requiredOne of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months.
letter_kind"permanent" | "fixed_term"requiredOffer letters: the contract kind Hiring uses it for (permanent; fixed_term, also temporary and internship contracts). null for other kinds.
approvalobject | nullrequiredA version waiting for approval, or sent back with a comment (when your company requires approval to publish).
7 fields
state"pending" | "rejected"requiredpending: waits for an approver; rejected: sent back (the draft is unchanged: change it and publish again).
approvers"hr" | "owner"requiredhr: an owner, admin or HR member; owner: an owner. Never whoever asked or changed the draft last.
versionintegerrequiredThe version it makes once approved.
asked_atstringrequiredasked_by_youbooleanrequiredcan_decidebooleanrequiredYou may approve it or send it back (signed in to Bizisy, an approver by the rule, not its asker or last editor).
decidedobject | nullrequiredWhen it was sent back, with the approver's comment.
2 fields
atstringrequiredcommentstring | nullrequired
style"international" | "continental"requiredThe default document style of what it makes: international (1. / 1.1 / (a)) or continental (Cláusula 1.ª / 1 – / a)). null: the company's default, else the country's. A style chosen when generating wins.
bodiesobject | nullrequiredEach language's title and body; null when the template uses pay details and you can't see pay.
6 fields
enobject2 fields
titlestringrequiredbodystringrequired
ptobject2 fields
titlestringrequiredbodystringrequired
esobject2 fields
titlestringrequiredbodystringrequired
frobject2 fields
titlestringrequiredbodystringrequired
deobject2 fields
titlestringrequiredbodystringrequired
itobject2 fields
titlestringrequiredbodystringrequired
body_hiddenbooleanrequiredversionsobject[]requiredPublished versions, newest first (built-ins: none listed).
3 fields
versionintegerrequiredpublished_atstringrequiredtier"public" | "job" | "private" | "pay"required
problemsobject[]requiredWarnings in the draft (errors are refused when saving).
8 fields
language"en" | "pt" | "es" | "fr" | "de" | "it"requiredfield"title" | "body"requiredlineintegerrequiredcolintegerrequiredcodestringrequiredmessagestringrequiredEnglish; the app translates by code.
severity"error" | "warning"requiredparamsobject
fieldsstring[]requiredThe fields the template uses.
lawobject[]requiredPer country it is for (EU: the Directive minimum when it is for every country).
11 fields
countrystringrequiredThe country whose rules apply (EU: Directive 2019/1152, for any other country).
reviewedbooleanrequiredA local employment lawyer checked this country's rules.
coveredobject[]required6 fields
idstringrequiredlabelstringrequiredEnglish; the app translates it.
requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requirednotestring | nullrequired
missingobject[]requiredRequired items the template does not cover.
6 fields
idstringrequiredlabelstringrequiredEnglish; the app translates it.
requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requirednotestring | nullrequired
optionalobject[]requiredItems needed only sometimes (fixed-term, probation…) that it does not cover.
6 fields
idstringrequiredlabelstringrequiredEnglish; the app translates it.
requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requirednotestring | nullrequired
manualobject[]requiredItems Bizisy cannot check by field: make sure the text says them.
6 fields
idstringrequiredlabelstringrequiredEnglish; the app translates it.
requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requirednotestring | nullrequired
signatureobjectrequired6 fields
min_level"none" | "simple" | "advanced" | "qualified" | "wet"requiredThe lowest signature level that makes it valid (wet: printed and signed by hand).
whostring[]requirednotestringrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requiredOnly verified rules block; others warn.
alternativesstring[]required
deliveryobjectrequired3 fields
deadlinestringrequiredbefore_start, on_start, days_after_start, by_effective_date, before_end, on_last_day, on_request or none.
proof_requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
languageobjectrequired3 fields
mandatorystring | nullrequireddefaultstring | nullrequiredtranslation_allowedbooleanrequired
dueobject[]requiredFor a person: by when each part must reach them.
2 fields
partstringrequiredduestringrequired
disclaimerstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/templates.create \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"kind": "contract_open",
"name": "Contract",
"category": "Contract",
"bodies": {
"en": {
"title": "Contract",
"body": "{{#clauses \"optional\"}}"
}
},
"slots": [
{
"name": "optional",
"allowed": [
"confidentiality",
"non_compete"
],
"defaults": [
"confidentiality"
]
}
],
"style": "international"
}'const res = await fetch('https://api.bizisy.com/v1/documents/templates.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"kind": "contract_open",
"name": "Contract",
"category": "Contract",
"bodies": {
"en": {
"title": "Contract",
"body": "{{#clauses \"optional\"}}"
}
},
"slots": [
{
"name": "optional",
"allowed": [
"confidentiality",
"non_compete"
],
"defaults": [
"confidentiality"
]
}
],
"style": "international"
}),
});
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/documents/templates.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"kind": "contract_open",
"name": "Contract",
"category": "Contract",
"bodies": {
"en": {
"title": "Contract",
"body": "{{#clauses \"optional\"}}",
},
},
"slots": [
{
"name": "optional",
"allowed": [
"confidentiality",
"non_compete",
],
"defaults": [
"confidentiality",
],
},
],
"style": "international",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "tpl1",
"source": "company",
"kind": "contract_open",
"name": "Contract",
"category": "Contract",
"countries": [
"PT"
],
"languages": [
"pt",
"en"
],
"signers": [
{
"role": "employer"
},
{
"role": "person"
}
],
"visibility": "hr_person",
"status": "draft",
"version": 0,
"has_draft": true,
"tier": "pay",
"reviewed": null,
"builtin_from": "builtin:letter-all-employment",
"updated_at": "2026-10-19T10:00:00.000Z",
"slots": [
{
"name": "optional",
"allowed": [
"confidentiality",
"non_compete"
],
"defaults": [
"confidentiality"
]
}
],
"letter_kind": null,
"approval": {
"state": "pending",
"approvers": "hr",
"version": 3,
"asked_at": "2026-10-19T11:00:00.000Z",
"asked_by_you": true,
"can_decide": false,
"decided": null
},
"style": "international",
"bodies": {
"pt": {
"title": "Contrato a termo – {{person.full_name}}",
"body": "# Contrato de trabalho a termo certo\n\n{{employer.legal_name}} e {{person.full_name}}…\n\n{{signature.employer}}\n\n{{signature.person}}\n"
}
},
"body_hidden": false,
"versions": [],
"problems": [
{
"language": "pt",
"field": "body",
"line": 3,
"col": 1,
"code": "long_word",
"message": "\"…\" is too long for a line; it will be cut where the page ends.",
"severity": "warning",
"params": {
"word": "x"
}
}
],
"fields": [
"employer.legal_name",
"person.full_name"
],
"law": [
{
"country": "PT",
"reviewed": false,
"covered": [
{
"id": "parties.person",
"label": "The employee's identity",
"required": true,
"source": {
"url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
"article": "Código do Trabalho, art. 141"
},
"confidence": "verified",
"note": null
}
],
"missing": [
{
"id": "reason_for_term",
"label": "The reason for the fixed term",
"required": true,
"source": {
"url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
"article": "Código do Trabalho, art. 141"
},
"confidence": "verified",
"note": "Name the specific facts that justify the term."
}
],
"optional": [],
"manual": [],
"signature": {
"min_level": "qualified",
"who": [
"employer",
"person"
],
"note": "Written form: both sign with a qualified electronic signature or print and sign by hand.",
"source": {
"url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
"article": "Código do Trabalho, art. 141"
},
"confidence": "verified",
"alternatives": [
"print"
]
},
"delivery": {
"deadline": "days_after_start",
"proof_required": true,
"source": {
"url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
"article": "Código do Trabalho, art. 141"
}
},
"language": {
"mandatory": null,
"default": "pt",
"translation_allowed": true
},
"due": [
{
"part": "all",
"due": "2026-11-09"
}
],
"disclaimer": "Bizisy checks the legal minimum it knows of. It is a starting point, not legal advice: have your templates checked."
}
]
}
}Edit a document template#
POST/v1/documents/templates.updateWrite
Edits the draft of one of your templates (send only what changes: name, category, countries, bodies (the whole set of languages: a language left out is removed), signers, visibility, style (the default document style: international or continental; null: the company's default, else the country's)). Published versions never change: publish the draft to make a new version. Lint errors refuse the save and list each problem. Built-ins can't be edited: copy them first. Same callers as documents_templates_create (an API key or AI assistant can't edit a template with pay details).
- Who can call it
- Manage key owner admin hr
- Keys and apps
- No templates with pay details.
- MCP tool
documents_templates_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
template_idstringrequirednamestring1–120 characters.
categorystring1–40 characters.
countriesstring[]1–30 items. Pattern
^([A-Z]{2}|\*)$.bodiesobject6 fields
enobject2 fields
titlestringrequiredThe generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".
1–200 characters.
bodystringrequiredThe template: Markdown-lite (# headings, - lists, | tables |, --- page break, **bold**, *italic*) with {{placeholders}}, {{#if path is value}}…{{else}}…{{/if}}, {{#each list}}…{{/each}} and {{signature.<role>}} blocks.
Up to 60000 characters.
ptobject2 fields
titlestringrequiredThe generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".
1–200 characters.
bodystringrequiredThe template: Markdown-lite (# headings, - lists, | tables |, --- page break, **bold**, *italic*) with {{placeholders}}, {{#if path is value}}…{{else}}…{{/if}}, {{#each list}}…{{/each}} and {{signature.<role>}} blocks.
Up to 60000 characters.
esobject2 fields
titlestringrequiredThe generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".
1–200 characters.
bodystringrequiredThe template: Markdown-lite (# headings, - lists, | tables |, --- page break, **bold**, *italic*) with {{placeholders}}, {{#if path is value}}…{{else}}…{{/if}}, {{#each list}}…{{/each}} and {{signature.<role>}} blocks.
Up to 60000 characters.
frobject2 fields
titlestringrequiredThe generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".
1–200 characters.
bodystringrequiredThe template: Markdown-lite (# headings, - lists, | tables |, --- page break, **bold**, *italic*) with {{placeholders}}, {{#if path is value}}…{{else}}…{{/if}}, {{#each list}}…{{/each}} and {{signature.<role>}} blocks.
Up to 60000 characters.
deobject2 fields
titlestringrequiredThe generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".
1–200 characters.
bodystringrequiredThe template: Markdown-lite (# headings, - lists, | tables |, --- page break, **bold**, *italic*) with {{placeholders}}, {{#if path is value}}…{{else}}…{{/if}}, {{#each list}}…{{/each}} and {{signature.<role>}} blocks.
Up to 60000 characters.
itobject2 fields
titlestringrequiredThe generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".
1–200 characters.
bodystringrequiredThe template: Markdown-lite (# headings, - lists, | tables |, --- page break, **bold**, *italic*) with {{placeholders}}, {{#if path is value}}…{{else}}…{{/if}}, {{#each list}}…{{/each}} and {{signature.<role>}} blocks.
Up to 60000 characters.
signersobject[]Up to 5 items.
5 fields (one of several shapes)
Option 1
role"employer"required
Option 2
role"person"required
Option 3
role"manager"required
Option 4
role"named"requiredperson_idstringrequired
visibility"hr" | "hr_person" | "hr_person_manager"slotsobject[]The whole set of clause slot settings (a slot left out allows every type, none ticked).
Up to 10 items.
3 fields
namestringrequired1–40 characters. Pattern
^[a-z][a-z0-9_]*$.allowedstring (enum)[]requiredThe clause types HR may tick in this slot.
One of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months. 1–16 items.defaultsstring (enum)[]requiredTicked by default, in order (each must be allowed).
One of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months. Up to 16 items.
style"international" | "continental"The default document style (international or continental); null: the company's default, else the country's.
Returns
26 fields
idstringrequiredA company template's id, or a built-in's (builtin:…).
source"builtin" | "company"requiredbuiltin: Bizisy's (copy it to change it); company: your own.
kindstring (enum)requiredcontract_open, contract_fixed, contract_part_time, statement, amendment, change_notice, end_notice, certificate, declaration, policy, letter, offer_letter (Hiring's offer letter: its fields only), or pay_review_letter (Salary reviews' letter: the review's fields review.* with the person's, sent at release).
One of:
contract_open,contract_fixed,contract_part_time,statement,amendment,change_notice,end_notice,certificate,declaration,policy,letter,offer_letter,pay_review_letter.namestringrequiredcategorystringrequiredThe Documents category the generated documents get.
countriesstring[]requiredThe countries it is for (* = every country).
languages"en" | "pt" | "es" | "fr" | "de" | "it"[]requiredsignersobject[]requiredWho signs, in order: employer, person, manager, or a named person.
5 fields (one of several shapes)
Option 1
role"employer"required
Option 2
role"person"required
Option 3
role"manager"required
Option 4
role"named"requiredperson_idstringrequired
visibility"hr" | "hr_person" | "hr_person_manager"requiredWho sees the generated documents: hr, hr_person (default) or hr_person_manager.
status"draft" | "published" | "archived"requiredversionintegerrequiredThe latest published version (0: never published).
has_draftbooleanrequiredThe draft has changes not published yet.
tier"public" | "job" | "private" | "pay"requiredThe most sensitive fields it uses: public, job, private or pay. Pay templates are for those who see pay; private and pay ones are generated in the web app only.
reviewedboolean | nullrequiredBuilt-ins: a local employment lawyer reviewed the text (false: not yet). null for your own.
builtin_fromstring | nullrequiredThe template it was copied from.
updated_atstring | nullrequiredslotsobject[]requiredClause slots ({{#clauses "name"}}): the clause types HR may pick there when generating, and the ones ticked by default.
3 fields
namestringrequiredallowedstring (enum)[]requiredOne of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months.defaultsstring (enum)[]requiredOne of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months.
letter_kind"permanent" | "fixed_term"requiredOffer letters: the contract kind Hiring uses it for (permanent; fixed_term, also temporary and internship contracts). null for other kinds.
approvalobject | nullrequiredA version waiting for approval, or sent back with a comment (when your company requires approval to publish).
7 fields
state"pending" | "rejected"requiredpending: waits for an approver; rejected: sent back (the draft is unchanged: change it and publish again).
approvers"hr" | "owner"requiredhr: an owner, admin or HR member; owner: an owner. Never whoever asked or changed the draft last.
versionintegerrequiredThe version it makes once approved.
asked_atstringrequiredasked_by_youbooleanrequiredcan_decidebooleanrequiredYou may approve it or send it back (signed in to Bizisy, an approver by the rule, not its asker or last editor).
decidedobject | nullrequiredWhen it was sent back, with the approver's comment.
2 fields
atstringrequiredcommentstring | nullrequired
style"international" | "continental"requiredThe default document style of what it makes: international (1. / 1.1 / (a)) or continental (Cláusula 1.ª / 1 – / a)). null: the company's default, else the country's. A style chosen when generating wins.
bodiesobject | nullrequiredEach language's title and body; null when the template uses pay details and you can't see pay.
6 fields
enobject2 fields
titlestringrequiredbodystringrequired
ptobject2 fields
titlestringrequiredbodystringrequired
esobject2 fields
titlestringrequiredbodystringrequired
frobject2 fields
titlestringrequiredbodystringrequired
deobject2 fields
titlestringrequiredbodystringrequired
itobject2 fields
titlestringrequiredbodystringrequired
body_hiddenbooleanrequiredversionsobject[]requiredPublished versions, newest first (built-ins: none listed).
3 fields
versionintegerrequiredpublished_atstringrequiredtier"public" | "job" | "private" | "pay"required
problemsobject[]requiredWarnings in the draft (errors are refused when saving).
8 fields
language"en" | "pt" | "es" | "fr" | "de" | "it"requiredfield"title" | "body"requiredlineintegerrequiredcolintegerrequiredcodestringrequiredmessagestringrequiredEnglish; the app translates by code.
severity"error" | "warning"requiredparamsobject
fieldsstring[]requiredThe fields the template uses.
lawobject[]requiredPer country it is for (EU: the Directive minimum when it is for every country).
11 fields
countrystringrequiredThe country whose rules apply (EU: Directive 2019/1152, for any other country).
reviewedbooleanrequiredA local employment lawyer checked this country's rules.
coveredobject[]required6 fields
idstringrequiredlabelstringrequiredEnglish; the app translates it.
requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requirednotestring | nullrequired
missingobject[]requiredRequired items the template does not cover.
6 fields
idstringrequiredlabelstringrequiredEnglish; the app translates it.
requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requirednotestring | nullrequired
optionalobject[]requiredItems needed only sometimes (fixed-term, probation…) that it does not cover.
6 fields
idstringrequiredlabelstringrequiredEnglish; the app translates it.
requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requirednotestring | nullrequired
manualobject[]requiredItems Bizisy cannot check by field: make sure the text says them.
6 fields
idstringrequiredlabelstringrequiredEnglish; the app translates it.
requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requirednotestring | nullrequired
signatureobjectrequired6 fields
min_level"none" | "simple" | "advanced" | "qualified" | "wet"requiredThe lowest signature level that makes it valid (wet: printed and signed by hand).
whostring[]requirednotestringrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requiredOnly verified rules block; others warn.
alternativesstring[]required
deliveryobjectrequired3 fields
deadlinestringrequiredbefore_start, on_start, days_after_start, by_effective_date, before_end, on_last_day, on_request or none.
proof_requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
languageobjectrequired3 fields
mandatorystring | nullrequireddefaultstring | nullrequiredtranslation_allowedbooleanrequired
dueobject[]requiredFor a person: by when each part must reach them.
2 fields
partstringrequiredduestringrequired
disclaimerstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/templates.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"template_id": "tpl1",
"bodies": {
"en": {
"title": "Contract",
"body": "x"
}
},
"countries": [
"*"
],
"signers": [
{
"role": "person"
}
],
"visibility": "hr"
}'const res = await fetch('https://api.bizisy.com/v1/documents/templates.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"template_id": "tpl1",
"bodies": {
"en": {
"title": "Contract",
"body": "x"
}
},
"countries": [
"*"
],
"signers": [
{
"role": "person"
}
],
"visibility": "hr"
}),
});
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/documents/templates.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"template_id": "tpl1",
"bodies": {
"en": {
"title": "Contract",
"body": "x",
},
},
"countries": [
"*",
],
"signers": [
{
"role": "person",
},
],
"visibility": "hr",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "tpl1",
"source": "company",
"kind": "contract_fixed",
"name": "Fixed-term contract (PT)",
"category": "Contract",
"countries": [
"PT"
],
"languages": [
"pt",
"en"
],
"signers": [
{
"role": "employer"
},
{
"role": "person"
}
],
"visibility": "hr",
"status": "published",
"version": 2,
"has_draft": true,
"tier": "pay",
"reviewed": null,
"builtin_from": "builtin:letter-all-employment",
"updated_at": "2026-10-19T10:00:00.000Z",
"slots": [
{
"name": "optional",
"allowed": [
"confidentiality",
"non_compete"
],
"defaults": [
"confidentiality"
]
}
],
"letter_kind": null,
"approval": {
"state": "pending",
"approvers": "hr",
"version": 3,
"asked_at": "2026-10-19T11:00:00.000Z",
"asked_by_you": true,
"can_decide": false,
"decided": null
},
"style": "continental",
"bodies": {
"pt": {
"title": "Contrato a termo – {{person.full_name}}",
"body": "# Contrato de trabalho a termo certo\n\n{{employer.legal_name}} e {{person.full_name}}…\n\n{{signature.employer}}\n\n{{signature.person}}\n"
}
},
"body_hidden": false,
"versions": [
{
"version": 2,
"published_at": "2026-10-19T10:00:00.000Z",
"tier": "pay"
},
{
"version": 1,
"published_at": "2026-10-18T10:00:00.000Z",
"tier": "pay"
}
],
"problems": [
{
"language": "pt",
"field": "body",
"line": 3,
"col": 1,
"code": "long_word",
"message": "\"…\" is too long for a line; it will be cut where the page ends.",
"severity": "warning",
"params": {
"word": "x"
}
}
],
"fields": [
"employer.legal_name",
"person.full_name"
],
"law": [
{
"country": "PT",
"reviewed": false,
"covered": [
{
"id": "parties.person",
"label": "The employee's identity",
"required": true,
"source": {
"url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
"article": "Código do Trabalho, art. 141"
},
"confidence": "verified",
"note": null
}
],
"missing": [
{
"id": "reason_for_term",
"label": "The reason for the fixed term",
"required": true,
"source": {
"url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
"article": "Código do Trabalho, art. 141"
},
"confidence": "verified",
"note": "Name the specific facts that justify the term."
}
],
"optional": [],
"manual": [],
"signature": {
"min_level": "qualified",
"who": [
"employer",
"person"
],
"note": "Written form: both sign with a qualified electronic signature or print and sign by hand.",
"source": {
"url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
"article": "Código do Trabalho, art. 141"
},
"confidence": "verified",
"alternatives": [
"print"
]
},
"delivery": {
"deadline": "days_after_start",
"proof_required": true,
"source": {
"url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
"article": "Código do Trabalho, art. 141"
}
},
"language": {
"mandatory": null,
"default": "pt",
"translation_allowed": true
},
"due": [
{
"part": "all",
"due": "2026-11-09"
}
],
"disclaimer": "Bizisy checks the legal minimum it knows of. It is a starting point, not legal advice: have your templates checked."
}
]
}
}Copy a document template#
POST/v1/documents/templates.copyWrite
Makes a draft copy of a built-in template (to adapt Bizisy's text) or of one of yours (its draft): same kind, category, countries, bodies, signers, visibility and default style; name optional (default: the original's with "(copy)"). Same callers as documents_templates_create.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_templates_copyon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
template_idstringrequirednamestring1–120 characters.
Returns
26 fields
idstringrequiredA company template's id, or a built-in's (builtin:…).
source"builtin" | "company"requiredbuiltin: Bizisy's (copy it to change it); company: your own.
kindstring (enum)requiredcontract_open, contract_fixed, contract_part_time, statement, amendment, change_notice, end_notice, certificate, declaration, policy, letter, offer_letter (Hiring's offer letter: its fields only), or pay_review_letter (Salary reviews' letter: the review's fields review.* with the person's, sent at release).
One of:
contract_open,contract_fixed,contract_part_time,statement,amendment,change_notice,end_notice,certificate,declaration,policy,letter,offer_letter,pay_review_letter.namestringrequiredcategorystringrequiredThe Documents category the generated documents get.
countriesstring[]requiredThe countries it is for (* = every country).
languages"en" | "pt" | "es" | "fr" | "de" | "it"[]requiredsignersobject[]requiredWho signs, in order: employer, person, manager, or a named person.
5 fields (one of several shapes)
Option 1
role"employer"required
Option 2
role"person"required
Option 3
role"manager"required
Option 4
role"named"requiredperson_idstringrequired
visibility"hr" | "hr_person" | "hr_person_manager"requiredWho sees the generated documents: hr, hr_person (default) or hr_person_manager.
status"draft" | "published" | "archived"requiredversionintegerrequiredThe latest published version (0: never published).
has_draftbooleanrequiredThe draft has changes not published yet.
tier"public" | "job" | "private" | "pay"requiredThe most sensitive fields it uses: public, job, private or pay. Pay templates are for those who see pay; private and pay ones are generated in the web app only.
reviewedboolean | nullrequiredBuilt-ins: a local employment lawyer reviewed the text (false: not yet). null for your own.
builtin_fromstring | nullrequiredThe template it was copied from.
updated_atstring | nullrequiredslotsobject[]requiredClause slots ({{#clauses "name"}}): the clause types HR may pick there when generating, and the ones ticked by default.
3 fields
namestringrequiredallowedstring (enum)[]requiredOne of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months.defaultsstring (enum)[]requiredOne of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months.
letter_kind"permanent" | "fixed_term"requiredOffer letters: the contract kind Hiring uses it for (permanent; fixed_term, also temporary and internship contracts). null for other kinds.
approvalobject | nullrequiredA version waiting for approval, or sent back with a comment (when your company requires approval to publish).
7 fields
state"pending" | "rejected"requiredpending: waits for an approver; rejected: sent back (the draft is unchanged: change it and publish again).
approvers"hr" | "owner"requiredhr: an owner, admin or HR member; owner: an owner. Never whoever asked or changed the draft last.
versionintegerrequiredThe version it makes once approved.
asked_atstringrequiredasked_by_youbooleanrequiredcan_decidebooleanrequiredYou may approve it or send it back (signed in to Bizisy, an approver by the rule, not its asker or last editor).
decidedobject | nullrequiredWhen it was sent back, with the approver's comment.
2 fields
atstringrequiredcommentstring | nullrequired
style"international" | "continental"requiredThe default document style of what it makes: international (1. / 1.1 / (a)) or continental (Cláusula 1.ª / 1 – / a)). null: the company's default, else the country's. A style chosen when generating wins.
bodiesobject | nullrequiredEach language's title and body; null when the template uses pay details and you can't see pay.
6 fields
enobject2 fields
titlestringrequiredbodystringrequired
ptobject2 fields
titlestringrequiredbodystringrequired
esobject2 fields
titlestringrequiredbodystringrequired
frobject2 fields
titlestringrequiredbodystringrequired
deobject2 fields
titlestringrequiredbodystringrequired
itobject2 fields
titlestringrequiredbodystringrequired
body_hiddenbooleanrequiredversionsobject[]requiredPublished versions, newest first (built-ins: none listed).
3 fields
versionintegerrequiredpublished_atstringrequiredtier"public" | "job" | "private" | "pay"required
problemsobject[]requiredWarnings in the draft (errors are refused when saving).
8 fields
language"en" | "pt" | "es" | "fr" | "de" | "it"requiredfield"title" | "body"requiredlineintegerrequiredcolintegerrequiredcodestringrequiredmessagestringrequiredEnglish; the app translates by code.
severity"error" | "warning"requiredparamsobject
fieldsstring[]requiredThe fields the template uses.
lawobject[]requiredPer country it is for (EU: the Directive minimum when it is for every country).
11 fields
countrystringrequiredThe country whose rules apply (EU: Directive 2019/1152, for any other country).
reviewedbooleanrequiredA local employment lawyer checked this country's rules.
coveredobject[]required6 fields
idstringrequiredlabelstringrequiredEnglish; the app translates it.
requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requirednotestring | nullrequired
missingobject[]requiredRequired items the template does not cover.
6 fields
idstringrequiredlabelstringrequiredEnglish; the app translates it.
requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requirednotestring | nullrequired
optionalobject[]requiredItems needed only sometimes (fixed-term, probation…) that it does not cover.
6 fields
idstringrequiredlabelstringrequiredEnglish; the app translates it.
requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requirednotestring | nullrequired
manualobject[]requiredItems Bizisy cannot check by field: make sure the text says them.
6 fields
idstringrequiredlabelstringrequiredEnglish; the app translates it.
requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requirednotestring | nullrequired
signatureobjectrequired6 fields
min_level"none" | "simple" | "advanced" | "qualified" | "wet"requiredThe lowest signature level that makes it valid (wet: printed and signed by hand).
whostring[]requirednotestringrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requiredOnly verified rules block; others warn.
alternativesstring[]required
deliveryobjectrequired3 fields
deadlinestringrequiredbefore_start, on_start, days_after_start, by_effective_date, before_end, on_last_day, on_request or none.
proof_requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
languageobjectrequired3 fields
mandatorystring | nullrequireddefaultstring | nullrequiredtranslation_allowedbooleanrequired
dueobject[]requiredFor a person: by when each part must reach them.
2 fields
partstringrequiredduestringrequired
disclaimerstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/templates.copy \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"template_id":"tpl1","name":"Fixed-term (copy)"}'const res = await fetch('https://api.bizisy.com/v1/documents/templates.copy', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"template_id": "tpl1",
"name": "Fixed-term (copy)"
}),
});
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/documents/templates.copy",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"template_id": "tpl1",
"name": "Fixed-term (copy)",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "tpl1",
"source": "company",
"kind": "contract_fixed",
"name": "Fixed-term (copy)",
"category": "Contract",
"countries": [
"PT"
],
"languages": [
"pt",
"en"
],
"signers": [
{
"role": "employer"
},
{
"role": "person"
}
],
"visibility": "hr_person",
"status": "draft",
"version": 0,
"has_draft": true,
"tier": "pay",
"reviewed": null,
"builtin_from": "builtin:letter-all-employment",
"updated_at": "2026-10-19T10:00:00.000Z",
"slots": [
{
"name": "optional",
"allowed": [
"confidentiality",
"non_compete"
],
"defaults": [
"confidentiality"
]
}
],
"letter_kind": null,
"approval": {
"state": "pending",
"approvers": "hr",
"version": 3,
"asked_at": "2026-10-19T11:00:00.000Z",
"asked_by_you": true,
"can_decide": false,
"decided": null
},
"style": "continental",
"bodies": {
"pt": {
"title": "Contrato a termo – {{person.full_name}}",
"body": "# Contrato de trabalho a termo certo\n\n{{employer.legal_name}} e {{person.full_name}}…\n\n{{signature.employer}}\n\n{{signature.person}}\n"
}
},
"body_hidden": false,
"versions": [],
"problems": [
{
"language": "pt",
"field": "body",
"line": 3,
"col": 1,
"code": "long_word",
"message": "\"…\" is too long for a line; it will be cut where the page ends.",
"severity": "warning",
"params": {
"word": "x"
}
}
],
"fields": [
"employer.legal_name",
"person.full_name"
],
"law": [
{
"country": "PT",
"reviewed": false,
"covered": [
{
"id": "parties.person",
"label": "The employee's identity",
"required": true,
"source": {
"url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
"article": "Código do Trabalho, art. 141"
},
"confidence": "verified",
"note": null
}
],
"missing": [
{
"id": "reason_for_term",
"label": "The reason for the fixed term",
"required": true,
"source": {
"url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
"article": "Código do Trabalho, art. 141"
},
"confidence": "verified",
"note": "Name the specific facts that justify the term."
}
],
"optional": [],
"manual": [],
"signature": {
"min_level": "qualified",
"who": [
"employer",
"person"
],
"note": "Written form: both sign with a qualified electronic signature or print and sign by hand.",
"source": {
"url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
"article": "Código do Trabalho, art. 141"
},
"confidence": "verified",
"alternatives": [
"print"
]
},
"delivery": {
"deadline": "days_after_start",
"proof_required": true,
"source": {
"url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
"article": "Código do Trabalho, art. 141"
}
},
"language": {
"mandatory": null,
"default": "pt",
"translation_allowed": true
},
"due": [
{
"part": "all",
"due": "2026-11-09"
}
],
"disclaimer": "Bizisy checks the legal minimum it knows of. It is a starting point, not legal advice: have your templates checked."
}
]
}
}Archive a document template#
POST/v1/documents/templates.archiveWrite
Archives one of your templates (archived false restores it): it leaves the library and can't generate documents; documents made from it and its versions stay. Same callers as documents_templates_create.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_templates_archiveon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
template_idstringrequiredarchivedbooleanDefault true; false restores it.
Returns
26 fields
idstringrequiredA company template's id, or a built-in's (builtin:…).
source"builtin" | "company"requiredbuiltin: Bizisy's (copy it to change it); company: your own.
kindstring (enum)requiredcontract_open, contract_fixed, contract_part_time, statement, amendment, change_notice, end_notice, certificate, declaration, policy, letter, offer_letter (Hiring's offer letter: its fields only), or pay_review_letter (Salary reviews' letter: the review's fields review.* with the person's, sent at release).
One of:
contract_open,contract_fixed,contract_part_time,statement,amendment,change_notice,end_notice,certificate,declaration,policy,letter,offer_letter,pay_review_letter.namestringrequiredcategorystringrequiredThe Documents category the generated documents get.
countriesstring[]requiredThe countries it is for (* = every country).
languages"en" | "pt" | "es" | "fr" | "de" | "it"[]requiredsignersobject[]requiredWho signs, in order: employer, person, manager, or a named person.
5 fields (one of several shapes)
Option 1
role"employer"required
Option 2
role"person"required
Option 3
role"manager"required
Option 4
role"named"requiredperson_idstringrequired
visibility"hr" | "hr_person" | "hr_person_manager"requiredWho sees the generated documents: hr, hr_person (default) or hr_person_manager.
status"draft" | "published" | "archived"requiredversionintegerrequiredThe latest published version (0: never published).
has_draftbooleanrequiredThe draft has changes not published yet.
tier"public" | "job" | "private" | "pay"requiredThe most sensitive fields it uses: public, job, private or pay. Pay templates are for those who see pay; private and pay ones are generated in the web app only.
reviewedboolean | nullrequiredBuilt-ins: a local employment lawyer reviewed the text (false: not yet). null for your own.
builtin_fromstring | nullrequiredThe template it was copied from.
updated_atstring | nullrequiredslotsobject[]requiredClause slots ({{#clauses "name"}}): the clause types HR may pick there when generating, and the ones ticked by default.
3 fields
namestringrequiredallowedstring (enum)[]requiredOne of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months.defaultsstring (enum)[]requiredOne of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months.
letter_kind"permanent" | "fixed_term"requiredOffer letters: the contract kind Hiring uses it for (permanent; fixed_term, also temporary and internship contracts). null for other kinds.
approvalobject | nullrequiredA version waiting for approval, or sent back with a comment (when your company requires approval to publish).
7 fields
state"pending" | "rejected"requiredpending: waits for an approver; rejected: sent back (the draft is unchanged: change it and publish again).
approvers"hr" | "owner"requiredhr: an owner, admin or HR member; owner: an owner. Never whoever asked or changed the draft last.
versionintegerrequiredThe version it makes once approved.
asked_atstringrequiredasked_by_youbooleanrequiredcan_decidebooleanrequiredYou may approve it or send it back (signed in to Bizisy, an approver by the rule, not its asker or last editor).
decidedobject | nullrequiredWhen it was sent back, with the approver's comment.
2 fields
atstringrequiredcommentstring | nullrequired
style"international" | "continental"requiredThe default document style of what it makes: international (1. / 1.1 / (a)) or continental (Cláusula 1.ª / 1 – / a)). null: the company's default, else the country's. A style chosen when generating wins.
bodiesobject | nullrequiredEach language's title and body; null when the template uses pay details and you can't see pay.
6 fields
enobject2 fields
titlestringrequiredbodystringrequired
ptobject2 fields
titlestringrequiredbodystringrequired
esobject2 fields
titlestringrequiredbodystringrequired
frobject2 fields
titlestringrequiredbodystringrequired
deobject2 fields
titlestringrequiredbodystringrequired
itobject2 fields
titlestringrequiredbodystringrequired
body_hiddenbooleanrequiredversionsobject[]requiredPublished versions, newest first (built-ins: none listed).
3 fields
versionintegerrequiredpublished_atstringrequiredtier"public" | "job" | "private" | "pay"required
problemsobject[]requiredWarnings in the draft (errors are refused when saving).
8 fields
language"en" | "pt" | "es" | "fr" | "de" | "it"requiredfield"title" | "body"requiredlineintegerrequiredcolintegerrequiredcodestringrequiredmessagestringrequiredEnglish; the app translates by code.
severity"error" | "warning"requiredparamsobject
fieldsstring[]requiredThe fields the template uses.
lawobject[]requiredPer country it is for (EU: the Directive minimum when it is for every country).
11 fields
countrystringrequiredThe country whose rules apply (EU: Directive 2019/1152, for any other country).
reviewedbooleanrequiredA local employment lawyer checked this country's rules.
coveredobject[]required6 fields
idstringrequiredlabelstringrequiredEnglish; the app translates it.
requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requirednotestring | nullrequired
missingobject[]requiredRequired items the template does not cover.
6 fields
idstringrequiredlabelstringrequiredEnglish; the app translates it.
requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requirednotestring | nullrequired
optionalobject[]requiredItems needed only sometimes (fixed-term, probation…) that it does not cover.
6 fields
idstringrequiredlabelstringrequiredEnglish; the app translates it.
requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requirednotestring | nullrequired
manualobject[]requiredItems Bizisy cannot check by field: make sure the text says them.
6 fields
idstringrequiredlabelstringrequiredEnglish; the app translates it.
requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requirednotestring | nullrequired
signatureobjectrequired6 fields
min_level"none" | "simple" | "advanced" | "qualified" | "wet"requiredThe lowest signature level that makes it valid (wet: printed and signed by hand).
whostring[]requirednotestringrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requiredOnly verified rules block; others warn.
alternativesstring[]required
deliveryobjectrequired3 fields
deadlinestringrequiredbefore_start, on_start, days_after_start, by_effective_date, before_end, on_last_day, on_request or none.
proof_requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
languageobjectrequired3 fields
mandatorystring | nullrequireddefaultstring | nullrequiredtranslation_allowedbooleanrequired
dueobject[]requiredFor a person: by when each part must reach them.
2 fields
partstringrequiredduestringrequired
disclaimerstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/templates.archive \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"template_id":"tpl1","archived":false}'const res = await fetch('https://api.bizisy.com/v1/documents/templates.archive', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"template_id": "tpl1",
"archived": false
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/documents/templates.archive",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"template_id": "tpl1",
"archived": False,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "tpl1",
"source": "company",
"kind": "contract_fixed",
"name": "Fixed-term contract (PT)",
"category": "Contract",
"countries": [
"PT"
],
"languages": [
"pt",
"en"
],
"signers": [
{
"role": "employer"
},
{
"role": "person"
}
],
"visibility": "hr_person",
"status": "archived",
"version": 2,
"has_draft": true,
"tier": "pay",
"reviewed": null,
"builtin_from": "builtin:letter-all-employment",
"updated_at": "2026-10-19T10:00:00.000Z",
"slots": [
{
"name": "optional",
"allowed": [
"confidentiality",
"non_compete"
],
"defaults": [
"confidentiality"
]
}
],
"letter_kind": null,
"approval": {
"state": "pending",
"approvers": "hr",
"version": 3,
"asked_at": "2026-10-19T11:00:00.000Z",
"asked_by_you": true,
"can_decide": false,
"decided": null
},
"style": "continental",
"bodies": {
"pt": {
"title": "Contrato a termo – {{person.full_name}}",
"body": "# Contrato de trabalho a termo certo\n\n{{employer.legal_name}} e {{person.full_name}}…\n\n{{signature.employer}}\n\n{{signature.person}}\n"
}
},
"body_hidden": false,
"versions": [
{
"version": 2,
"published_at": "2026-10-19T10:00:00.000Z",
"tier": "pay"
},
{
"version": 1,
"published_at": "2026-10-18T10:00:00.000Z",
"tier": "pay"
}
],
"problems": [
{
"language": "pt",
"field": "body",
"line": 3,
"col": 1,
"code": "long_word",
"message": "\"…\" is too long for a line; it will be cut where the page ends.",
"severity": "warning",
"params": {
"word": "x"
}
}
],
"fields": [
"employer.legal_name",
"person.full_name"
],
"law": [
{
"country": "PT",
"reviewed": false,
"covered": [
{
"id": "parties.person",
"label": "The employee's identity",
"required": true,
"source": {
"url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
"article": "Código do Trabalho, art. 141"
},
"confidence": "verified",
"note": null
}
],
"missing": [
{
"id": "reason_for_term",
"label": "The reason for the fixed term",
"required": true,
"source": {
"url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
"article": "Código do Trabalho, art. 141"
},
"confidence": "verified",
"note": "Name the specific facts that justify the term."
}
],
"optional": [],
"manual": [],
"signature": {
"min_level": "qualified",
"who": [
"employer",
"person"
],
"note": "Written form: both sign with a qualified electronic signature or print and sign by hand.",
"source": {
"url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
"article": "Código do Trabalho, art. 141"
},
"confidence": "verified",
"alternatives": [
"print"
]
},
"delivery": {
"deadline": "days_after_start",
"proof_required": true,
"source": {
"url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
"article": "Código do Trabalho, art. 141"
}
},
"language": {
"mandatory": null,
"default": "pt",
"translation_allowed": true
},
"due": [
{
"part": "all",
"due": "2026-11-09"
}
],
"disclaimer": "Bizisy checks the legal minimum it knows of. It is a starting point, not legal advice: have your templates checked."
}
]
}
}Publish a document template#
POST/v1/documents/templates.publishWrite
Publishes the draft of one of your templates as a new version (1, 2, …). Published versions never change; every generated document records the version it came from (documents_generated_list shows who has which). When your company requires approval (documents_templates_settings_get), the version waits instead (pending_approval true, published_version null) until an approver approves it in Approvals; its draft can't change meanwhile (documents_templates_withdraw takes it back). Refused with lint errors, when nothing changed since the last version, or when nobody else could approve it. Use dry_run to see the version it would make. At most 500 versions. Same callers as documents_templates_create.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_templates_publishon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
template_idstringrequired
Returns
28 fields
idstringrequiredA company template's id, or a built-in's (builtin:…).
source"builtin" | "company"requiredbuiltin: Bizisy's (copy it to change it); company: your own.
kindstring (enum)requiredcontract_open, contract_fixed, contract_part_time, statement, amendment, change_notice, end_notice, certificate, declaration, policy, letter, offer_letter (Hiring's offer letter: its fields only), or pay_review_letter (Salary reviews' letter: the review's fields review.* with the person's, sent at release).
One of:
contract_open,contract_fixed,contract_part_time,statement,amendment,change_notice,end_notice,certificate,declaration,policy,letter,offer_letter,pay_review_letter.namestringrequiredcategorystringrequiredThe Documents category the generated documents get.
countriesstring[]requiredThe countries it is for (* = every country).
languages"en" | "pt" | "es" | "fr" | "de" | "it"[]requiredsignersobject[]requiredWho signs, in order: employer, person, manager, or a named person.
5 fields (one of several shapes)
Option 1
role"employer"required
Option 2
role"person"required
Option 3
role"manager"required
Option 4
role"named"requiredperson_idstringrequired
visibility"hr" | "hr_person" | "hr_person_manager"requiredWho sees the generated documents: hr, hr_person (default) or hr_person_manager.
status"draft" | "published" | "archived"requiredversionintegerrequiredThe latest published version (0: never published).
has_draftbooleanrequiredThe draft has changes not published yet.
tier"public" | "job" | "private" | "pay"requiredThe most sensitive fields it uses: public, job, private or pay. Pay templates are for those who see pay; private and pay ones are generated in the web app only.
reviewedboolean | nullrequiredBuilt-ins: a local employment lawyer reviewed the text (false: not yet). null for your own.
builtin_fromstring | nullrequiredThe template it was copied from.
updated_atstring | nullrequiredslotsobject[]requiredClause slots ({{#clauses "name"}}): the clause types HR may pick there when generating, and the ones ticked by default.
3 fields
namestringrequiredallowedstring (enum)[]requiredOne of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months.defaultsstring (enum)[]requiredOne of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months.
letter_kind"permanent" | "fixed_term"requiredOffer letters: the contract kind Hiring uses it for (permanent; fixed_term, also temporary and internship contracts). null for other kinds.
approvalobject | nullrequiredA version waiting for approval, or sent back with a comment (when your company requires approval to publish).
7 fields
state"pending" | "rejected"requiredpending: waits for an approver; rejected: sent back (the draft is unchanged: change it and publish again).
approvers"hr" | "owner"requiredhr: an owner, admin or HR member; owner: an owner. Never whoever asked or changed the draft last.
versionintegerrequiredThe version it makes once approved.
asked_atstringrequiredasked_by_youbooleanrequiredcan_decidebooleanrequiredYou may approve it or send it back (signed in to Bizisy, an approver by the rule, not its asker or last editor).
decidedobject | nullrequiredWhen it was sent back, with the approver's comment.
2 fields
atstringrequiredcommentstring | nullrequired
style"international" | "continental"requiredThe default document style of what it makes: international (1. / 1.1 / (a)) or continental (Cláusula 1.ª / 1 – / a)). null: the company's default, else the country's. A style chosen when generating wins.
bodiesobject | nullrequiredEach language's title and body; null when the template uses pay details and you can't see pay.
6 fields
enobject2 fields
titlestringrequiredbodystringrequired
ptobject2 fields
titlestringrequiredbodystringrequired
esobject2 fields
titlestringrequiredbodystringrequired
frobject2 fields
titlestringrequiredbodystringrequired
deobject2 fields
titlestringrequiredbodystringrequired
itobject2 fields
titlestringrequiredbodystringrequired
body_hiddenbooleanrequiredversionsobject[]requiredPublished versions, newest first (built-ins: none listed).
3 fields
versionintegerrequiredpublished_atstringrequiredtier"public" | "job" | "private" | "pay"required
problemsobject[]requiredWarnings in the draft (errors are refused when saving).
8 fields
language"en" | "pt" | "es" | "fr" | "de" | "it"requiredfield"title" | "body"requiredlineintegerrequiredcolintegerrequiredcodestringrequiredmessagestringrequiredEnglish; the app translates by code.
severity"error" | "warning"requiredparamsobject
fieldsstring[]requiredThe fields the template uses.
lawobject[]requiredPer country it is for (EU: the Directive minimum when it is for every country).
11 fields
countrystringrequiredThe country whose rules apply (EU: Directive 2019/1152, for any other country).
reviewedbooleanrequiredA local employment lawyer checked this country's rules.
coveredobject[]required6 fields
idstringrequiredlabelstringrequiredEnglish; the app translates it.
requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requirednotestring | nullrequired
missingobject[]requiredRequired items the template does not cover.
6 fields
idstringrequiredlabelstringrequiredEnglish; the app translates it.
requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requirednotestring | nullrequired
optionalobject[]requiredItems needed only sometimes (fixed-term, probation…) that it does not cover.
6 fields
idstringrequiredlabelstringrequiredEnglish; the app translates it.
requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requirednotestring | nullrequired
manualobject[]requiredItems Bizisy cannot check by field: make sure the text says them.
6 fields
idstringrequiredlabelstringrequiredEnglish; the app translates it.
requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requirednotestring | nullrequired
signatureobjectrequired6 fields
min_level"none" | "simple" | "advanced" | "qualified" | "wet"requiredThe lowest signature level that makes it valid (wet: printed and signed by hand).
whostring[]requirednotestringrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requiredOnly verified rules block; others warn.
alternativesstring[]required
deliveryobjectrequired3 fields
deadlinestringrequiredbefore_start, on_start, days_after_start, by_effective_date, before_end, on_last_day, on_request or none.
proof_requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
languageobjectrequired3 fields
mandatorystring | nullrequireddefaultstring | nullrequiredtranslation_allowedbooleanrequired
dueobject[]requiredFor a person: by when each part must reach them.
2 fields
partstringrequiredduestringrequired
disclaimerstringrequired
published_versioninteger | nullrequiredThe version published; null when it waits for approval.
pending_approvalbooleanrequiredIt waits for an approver (your company requires approval to publish).
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/templates.publish \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"template_id":"tpl1"}'const res = await fetch('https://api.bizisy.com/v1/documents/templates.publish', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"template_id": "tpl1"
}),
});
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/documents/templates.publish",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"template_id": "tpl1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "tpl1",
"source": "company",
"kind": "contract_fixed",
"name": "Fixed-term contract (PT)",
"category": "Contract",
"countries": [
"PT"
],
"languages": [
"pt",
"en"
],
"signers": [
{
"role": "employer"
},
{
"role": "person"
}
],
"visibility": "hr_person",
"status": "published",
"version": 2,
"has_draft": false,
"tier": "pay",
"reviewed": null,
"builtin_from": "builtin:letter-all-employment",
"updated_at": "2026-10-19T10:00:00.000Z",
"slots": [
{
"name": "optional",
"allowed": [
"confidentiality",
"non_compete"
],
"defaults": [
"confidentiality"
]
}
],
"letter_kind": null,
"approval": {
"state": "pending",
"approvers": "hr",
"version": 3,
"asked_at": "2026-10-19T11:00:00.000Z",
"asked_by_you": true,
"can_decide": false,
"decided": null
},
"style": "continental",
"bodies": {
"pt": {
"title": "Contrato a termo – {{person.full_name}}",
"body": "# Contrato de trabalho a termo certo\n\n{{employer.legal_name}} e {{person.full_name}}…\n\n{{signature.employer}}\n\n{{signature.person}}\n"
}
},
"body_hidden": false,
"versions": [
{
"version": 2,
"published_at": "2026-10-19T10:00:00.000Z",
"tier": "pay"
},
{
"version": 1,
"published_at": "2026-10-18T10:00:00.000Z",
"tier": "pay"
}
],
"problems": [
{
"language": "pt",
"field": "body",
"line": 3,
"col": 1,
"code": "long_word",
"message": "\"…\" is too long for a line; it will be cut where the page ends.",
"severity": "warning",
"params": {
"word": "x"
}
}
],
"fields": [
"employer.legal_name",
"person.full_name"
],
"law": [
{
"country": "PT",
"reviewed": false,
"covered": [
{
"id": "parties.person",
"label": "The employee's identity",
"required": true,
"source": {
"url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
"article": "Código do Trabalho, art. 141"
},
"confidence": "verified",
"note": null
}
],
"missing": [
{
"id": "reason_for_term",
"label": "The reason for the fixed term",
"required": true,
"source": {
"url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
"article": "Código do Trabalho, art. 141"
},
"confidence": "verified",
"note": "Name the specific facts that justify the term."
}
],
"optional": [],
"manual": [],
"signature": {
"min_level": "qualified",
"who": [
"employer",
"person"
],
"note": "Written form: both sign with a qualified electronic signature or print and sign by hand.",
"source": {
"url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
"article": "Código do Trabalho, art. 141"
},
"confidence": "verified",
"alternatives": [
"print"
]
},
"delivery": {
"deadline": "days_after_start",
"proof_required": true,
"source": {
"url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
"article": "Código do Trabalho, art. 141"
}
},
"language": {
"mandatory": null,
"default": "pt",
"translation_allowed": true
},
"due": [
{
"part": "all",
"due": "2026-11-09"
}
],
"disclaimer": "Bizisy checks the legal minimum it knows of. It is a starting point, not legal advice: have your templates checked."
}
],
"published_version": 2,
"pending_approval": false
}
}Preview a document template#
POST/v1/documents/templates.previewRead
The whole document as HTML (A4 pages, what the PDF will look like), filled for a person (person_id) or for Bizisy's sample person (no person_id; names with accents and other marks), from a template (template_id; its draft, or version) or from a body you send (body, title, kind: to preview while editing). Also: problems (lint, with language, line, column), missing (fields with no value on lines that stay: generating needs them), dropped (lines left out because all their fields are empty), withheld (fields you may not see for that person: generating refuses them), the law panel for the person's country (or the template's first) and its deadlines for the person, the document style used (style), the one that applies without a choice (style_default) and a short example of each style's numbering in the document's language (style_hints). style: how clauses, paragraphs and items are numbered and cited, with labels in the document's language: international (1. / 1.1 / (a), "clause 3.2(a)") or continental (Cláusula 1.ª / 1 – / a), "alínea a) do n.º 2 da cláusula 3.ª"). Precedence: the style given here, else the template's default style, else the company's (documents_templates_settings_update), else the country's (Portugal, Spain, France and Italy continental; every other country international). A template with pay details is previewed in the web app only, and only by those who see pay; one with private details only for the sample person over an API key or AI assistant. Owners, admins and HR (and custom roles with Documents at Edit, for the people they cover).
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Not for templates with pay details; private details only for the sample person.
- MCP tool
documents_templates_previewon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
template_idstringversionintegerA published version (default: the draft; built-ins: their text).
At least 1.
bodystringUp to 60000 characters.
titlestringUp to 200 characters.
kindstring (enum)One of:
contract_open,contract_fixed,contract_part_time,statement,amendment,change_notice,end_notice,certificate,declaration,policy,letter,offer_letter,pay_review_letter.countriesstring[]1–30 items. Pattern
^([A-Z]{2}|\*)$.language"en" | "pt" | "es" | "fr" | "de" | "it"Default: the person's country's language, else your company's, else English.
person_idstringoverridesobjectValues for this document only, by field path (e.g. {"job.reason_for_term": "A seasonal peak"}).
clausesobjectThe clauses to put in (as
documents_generatetakes them, for this person): each slot's picks in order, and fixed clauses' fields. Default: each slot's defaults.2 fields
slotsobjectPer clause slot, the clauses in order (an empty list: none). A slot left out gets its defaults.
fixedobjectFixed clauses ({{clause "type"}}): their typed fields, or another clause of that type.
16 fields
non_competeobjectrequired2 fields
clause_idstring1–100 characters.
fieldsobject
non_solicitationobjectrequired2 fields
clause_idstring1–100 characters.
fieldsobject
probationobjectrequired2 fields
clause_idstring1–100 characters.
fieldsobject
training_repaymentobjectrequired2 fields
clause_idstring1–100 characters.
fieldsobject
remote_workobjectrequired2 fields
clause_idstring1–100 characters.
fieldsobject
exclusivityobjectrequired2 fields
clause_idstring1–100 characters.
fieldsobject
confidentialityobjectrequired2 fields
clause_idstring1–100 characters.
fieldsobject
ip_inventionsobjectrequired2 fields
clause_idstring1–100 characters.
fieldsobject
mobilityobjectrequired2 fields
clause_idstring1–100 characters.
fieldsobject
overtime_includedobjectrequired2 fields
clause_idstring1–100 characters.
fieldsobject
noticeobjectrequired2 fields
clause_idstring1–100 characters.
fieldsobject
garden_leaveobjectrequired2 fields
clause_idstring1–100 characters.
fieldsobject
equipmentobjectrequired2 fields
clause_idstring1–100 characters.
fieldsobject
monitoring_noticeobjectrequired2 fields
clause_idstring1–100 characters.
fieldsobject
collective_agreementobjectrequired2 fields
clause_idstring1–100 characters.
fieldsobject
pay_extra_monthsobjectrequired2 fields
clause_idstring1–100 characters.
fieldsobject
slotsobject[]With body: the slot settings being edited.
Up to 10 items.
3 fields
namestringrequired1–40 characters. Pattern
^[a-z][a-z0-9_]*$.allowedstring (enum)[]requiredThe clause types HR may tick in this slot.
One of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months. 1–16 items.defaultsstring (enum)[]requiredTicked by default, in order (each must be allowed).
One of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months. Up to 16 items.
style"international" | "continental"The document style to preview in (international or continental). Default: the template's, else the company's, else the country's (style_default).
Returns
14 fields
htmlstringrequiredtitlestringrequiredlanguage"en" | "pt" | "es" | "fr" | "de" | "it"requiredsamplebooleanrequiredFilled for Bizisy's sample person.
tier"public" | "job" | "private" | "pay"requiredproblemsobject[]required8 fields
language"en" | "pt" | "es" | "fr" | "de" | "it"requiredfield"title" | "body"requiredlineintegerrequiredcolintegerrequiredcodestringrequiredmessagestringrequiredEnglish; the app translates by code.
severity"error" | "warning"requiredparamsobject
missingstring[]requireddroppedstring[]requiredwithheldstring[]requiredlawobjectrequired11 fields
countrystringrequiredThe country whose rules apply (EU: Directive 2019/1152, for any other country).
reviewedbooleanrequiredA local employment lawyer checked this country's rules.
coveredobject[]required6 fields
idstringrequiredlabelstringrequiredEnglish; the app translates it.
requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requirednotestring | nullrequired
missingobject[]requiredRequired items the template does not cover.
6 fields
idstringrequiredlabelstringrequiredEnglish; the app translates it.
requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requirednotestring | nullrequired
optionalobject[]requiredItems needed only sometimes (fixed-term, probation…) that it does not cover.
6 fields
idstringrequiredlabelstringrequiredEnglish; the app translates it.
requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requirednotestring | nullrequired
manualobject[]requiredItems Bizisy cannot check by field: make sure the text says them.
6 fields
idstringrequiredlabelstringrequiredEnglish; the app translates it.
requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requirednotestring | nullrequired
signatureobjectrequired6 fields
min_level"none" | "simple" | "advanced" | "qualified" | "wet"requiredThe lowest signature level that makes it valid (wet: printed and signed by hand).
whostring[]requirednotestringrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requiredOnly verified rules block; others warn.
alternativesstring[]required
deliveryobjectrequired3 fields
deadlinestringrequiredbefore_start, on_start, days_after_start, by_effective_date, before_end, on_last_day, on_request or none.
proof_requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
languageobjectrequired3 fields
mandatorystring | nullrequireddefaultstring | nullrequiredtranslation_allowedbooleanrequired
dueobject[]requiredFor a person: by when each part must reach them.
2 fields
partstringrequiredduestringrequired
disclaimerstringrequired
clausesobject[]requiredThe clauses in it for this person: the variant of their country, the rules' result (blocks refuse generating), the law note.
18 fields
okbooleanrequiredNo block: the clause may go in the document.
countrystring (enum)requiredWhose rules ran: PT, ES, FR, DE, IT, NL, or EU (the EU minimum, for any other country).
One of:
PT,ES,FR,DE,IT,NL,EU.blocksobject[]requiredThe law Bizisy treats as settled is broken: the document is refused with it.
6 fields
rulestringrequiredmessagestringrequiredEnglish with {params}; the app translates it.
paramsobject | nullrequiredfieldstring | nullrequiredThe typed field it is about.
sourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"required
warnsobject[]requiredLess certain rules and reminders: the document is made, check with your lawyer.
6 fields
rulestringrequiredmessagestringrequiredEnglish with {params}; the app translates it.
paramsobject | nullrequiredfieldstring | nullrequiredThe typed field it is about.
sourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"required
raises_toobject | nullrequiredThe signature level the clause needs (e.g. a German non-compete: qualified or by hand).
3 fields
level"none" | "simple" | "advanced" | "qualified" | "wet"requiredconfidence"verified" | "medium" | "uncertain"requiredsourceobject | nullrequired2 fields
urlstringrequiredarticlestringrequired
tasksobject[]requiredTo do once signed (Italy: file the smart-working agreement within 5 days).
4 fields
idstringrequiredlabelstringrequireddays_after_startintegerrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
fieldsobjectrequiredThe fields as checked (defaults filled in).
slotstring | nullrequiredThe slot it is in (null: a fixed clause).
typestring (enum)requiredOne of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months.clause_idstringrequiredsource"builtin" | "company"requiredversionintegerrequirednamestringrequiredvariant_countrystring (enum)requiredWhose rules ran: the person's country, or EU.
One of:
PT,ES,FR,DE,IT,NL,EU.notestringrequiredWhat the law says there (English; the app translates it).
confidence"verified" | "medium" | "uncertain"requiredsourcesobject[]required2 fields
urlstringrequiredarticlestringrequired
other_countrybooleanrequiredYour clause was written for another country's rules; it still runs the person's.
style"international" | "continental"requiredThe style it is shown in.
style_default"international" | "continental"requiredThe style it gets without a choice: the template's default, else the company's, else the country's.
style_hintsobjectrequiredA short example of each style's numbering in the document's language, e.g. "1. · 1.1 · (a)".
2 fields
internationalstringrequiredcontinentalstringrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/templates.preview \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"template_id": "tpl1",
"person_id": "p1",
"clauses": {
"slots": {
"optional": [
{
"type": "non_compete",
"fields": {
"compensation_pct": 50
}
}
]
},
"fixed": {
"probation": {
"fields": {
"duration": 3
}
}
}
}
}'const res = await fetch('https://api.bizisy.com/v1/documents/templates.preview', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"template_id": "tpl1",
"person_id": "p1",
"clauses": {
"slots": {
"optional": [
{
"type": "non_compete",
"fields": {
"compensation_pct": 50
}
}
]
},
"fixed": {
"probation": {
"fields": {
"duration": 3
}
}
}
}
}),
});
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/documents/templates.preview",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"template_id": "tpl1",
"person_id": "p1",
"clauses": {
"slots": {
"optional": [
{
"type": "non_compete",
"fields": {
"compensation_pct": 50,
},
},
],
},
"fixed": {
"probation": {
"fields": {
"duration": 3,
},
},
},
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"html": "<!doctype html><html lang=\"pt\"><body>…</body></html>",
"title": "Contrato a termo – Ana Ferreira",
"language": "pt",
"sample": false,
"tier": "pay",
"problems": [],
"missing": [
"job.reason_for_term"
],
"dropped": [
"employer.collective_agreement"
],
"withheld": [],
"law": {
"country": "PT",
"reviewed": false,
"covered": [
{
"id": "parties.person",
"label": "The employee's identity",
"required": true,
"source": {
"url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
"article": "Código do Trabalho, art. 141"
},
"confidence": "verified",
"note": null
}
],
"missing": [
{
"id": "reason_for_term",
"label": "The reason for the fixed term",
"required": true,
"source": {
"url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
"article": "Código do Trabalho, art. 141"
},
"confidence": "verified",
"note": "Name the specific facts that justify the term."
}
],
"optional": [],
"manual": [],
"signature": {
"min_level": "qualified",
"who": [
"employer",
"person"
],
"note": "Written form: both sign with a qualified electronic signature or print and sign by hand.",
"source": {
"url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
"article": "Código do Trabalho, art. 141"
},
"confidence": "verified",
"alternatives": [
"print"
]
},
"delivery": {
"deadline": "days_after_start",
"proof_required": true,
"source": {
"url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
"article": "Código do Trabalho, art. 141"
}
},
"language": {
"mandatory": null,
"default": "pt",
"translation_allowed": true
},
"due": [
{
"part": "all",
"due": "2026-11-09"
}
],
"disclaimer": "Bizisy checks the legal minimum it knows of. It is a starting point, not legal advice: have your templates checked."
},
"clauses": [
{
"ok": true,
"country": "DE",
"blocks": [],
"warns": [],
"raises_to": {
"level": "qualified",
"confidence": "verified",
"source": {
"url": "https://www.gesetze-im-internet.de/bgb/__126a.html",
"article": "HGB §74 Abs. 1; BGB §§126, 126a"
}
},
"tasks": [],
"fields": {
"duration_months": 12,
"compensation_pct": 50,
"waiver": "none"
},
"slot": "optional",
"type": "non_compete",
"clause_id": "builtin:clause.de.non_compete",
"source": "builtin",
"version": 1,
"name": "Non-compete after leaving (Germany)",
"variant_country": "DE",
"note": "Written and signed, with the signed document handed over; at least 50% of the last total pay, monthly, for up to 2 years; never with a minor.",
"confidence": "medium",
"sources": [
{
"url": "https://www.gesetze-im-internet.de/hgb/__74.html",
"article": "HGB §74 Abs. 1 und 2"
}
],
"other_country": false
}
],
"style": "continental",
"style_default": "continental",
"style_hints": {
"international": "1. · 1.1 · (a)",
"continental": "Cláusula 1.ª · 1 – · a)"
}
}
}Check a document template#
POST/v1/documents/templates.checkRead
Lints a template and checks it against the law, without saving: send a template (template_id, optionally version) or a text (bodies per language, kind, countries). Returns problems (unknown fields with a suggestion, unclosed blocks, operators that don't fit a field, fields not allowed in titles, words too long for a line), its tier, the fields it uses, and the law panel per country (items covered and missing, minimum signature level, delivery deadline, language). Pure: reads no person. API keys and AI assistants may use it. The law panel is a starting point, not legal advice.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_templates_checkon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
template_idstringversionintegerAt least 1.
bodiesobject6 fields
enobject2 fields
titlestringrequiredThe generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".
1–200 characters.
bodystringrequiredThe template: Markdown-lite (# headings, - lists, | tables |, --- page break, **bold**, *italic*) with {{placeholders}}, {{#if path is value}}…{{else}}…{{/if}}, {{#each list}}…{{/each}} and {{signature.<role>}} blocks.
Up to 60000 characters.
ptobject2 fields
titlestringrequiredThe generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".
1–200 characters.
bodystringrequiredThe template: Markdown-lite (# headings, - lists, | tables |, --- page break, **bold**, *italic*) with {{placeholders}}, {{#if path is value}}…{{else}}…{{/if}}, {{#each list}}…{{/each}} and {{signature.<role>}} blocks.
Up to 60000 characters.
esobject2 fields
titlestringrequiredThe generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".
1–200 characters.
bodystringrequiredThe template: Markdown-lite (# headings, - lists, | tables |, --- page break, **bold**, *italic*) with {{placeholders}}, {{#if path is value}}…{{else}}…{{/if}}, {{#each list}}…{{/each}} and {{signature.<role>}} blocks.
Up to 60000 characters.
frobject2 fields
titlestringrequiredThe generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".
1–200 characters.
bodystringrequiredThe template: Markdown-lite (# headings, - lists, | tables |, --- page break, **bold**, *italic*) with {{placeholders}}, {{#if path is value}}…{{else}}…{{/if}}, {{#each list}}…{{/each}} and {{signature.<role>}} blocks.
Up to 60000 characters.
deobject2 fields
titlestringrequiredThe generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".
1–200 characters.
bodystringrequiredThe template: Markdown-lite (# headings, - lists, | tables |, --- page break, **bold**, *italic*) with {{placeholders}}, {{#if path is value}}…{{else}}…{{/if}}, {{#each list}}…{{/each}} and {{signature.<role>}} blocks.
Up to 60000 characters.
itobject2 fields
titlestringrequiredThe generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".
1–200 characters.
bodystringrequiredThe template: Markdown-lite (# headings, - lists, | tables |, --- page break, **bold**, *italic*) with {{placeholders}}, {{#if path is value}}…{{else}}…{{/if}}, {{#each list}}…{{/each}} and {{signature.<role>}} blocks.
Up to 60000 characters.
kindstring (enum)One of:
contract_open,contract_fixed,contract_part_time,statement,amendment,change_notice,end_notice,certificate,declaration,policy,letter,offer_letter,pay_review_letter.countriesstring[]1–30 items. Pattern
^([A-Z]{2}|\*)$.
Returns
problemsobject[]required8 fields
language"en" | "pt" | "es" | "fr" | "de" | "it"requiredfield"title" | "body"requiredlineintegerrequiredcolintegerrequiredcodestringrequiredmessagestringrequiredEnglish; the app translates by code.
severity"error" | "warning"requiredparamsobject
tier"public" | "job" | "private" | "pay"requiredfieldsstring[]requiredlawobject[]required11 fields
countrystringrequiredThe country whose rules apply (EU: Directive 2019/1152, for any other country).
reviewedbooleanrequiredA local employment lawyer checked this country's rules.
coveredobject[]required6 fields
idstringrequiredlabelstringrequiredEnglish; the app translates it.
requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requirednotestring | nullrequired
missingobject[]requiredRequired items the template does not cover.
6 fields
idstringrequiredlabelstringrequiredEnglish; the app translates it.
requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requirednotestring | nullrequired
optionalobject[]requiredItems needed only sometimes (fixed-term, probation…) that it does not cover.
6 fields
idstringrequiredlabelstringrequiredEnglish; the app translates it.
requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requirednotestring | nullrequired
manualobject[]requiredItems Bizisy cannot check by field: make sure the text says them.
6 fields
idstringrequiredlabelstringrequiredEnglish; the app translates it.
requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requirednotestring | nullrequired
signatureobjectrequired6 fields
min_level"none" | "simple" | "advanced" | "qualified" | "wet"requiredThe lowest signature level that makes it valid (wet: printed and signed by hand).
whostring[]requirednotestringrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requiredOnly verified rules block; others warn.
alternativesstring[]required
deliveryobjectrequired3 fields
deadlinestringrequiredbefore_start, on_start, days_after_start, by_effective_date, before_end, on_last_day, on_request or none.
proof_requiredbooleanrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
languageobjectrequired3 fields
mandatorystring | nullrequireddefaultstring | nullrequiredtranslation_allowedbooleanrequired
dueobject[]requiredFor a person: by when each part must reach them.
2 fields
partstringrequiredduestringrequired
disclaimerstringrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/templates.check \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"bodies": {
"en": {
"title": "Contract",
"body": "{{person.full_name}}"
}
},
"kind": "contract_open",
"countries": [
"PT",
"DE"
]
}'const res = await fetch('https://api.bizisy.com/v1/documents/templates.check', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"bodies": {
"en": {
"title": "Contract",
"body": "{{person.full_name}}"
}
},
"kind": "contract_open",
"countries": [
"PT",
"DE"
]
}),
});
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/documents/templates.check",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"bodies": {
"en": {
"title": "Contract",
"body": "{{person.full_name}}",
},
},
"kind": "contract_open",
"countries": [
"PT",
"DE",
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"problems": [
{
"language": "pt",
"field": "body",
"line": 3,
"col": 1,
"code": "long_word",
"message": "\"…\" is too long for a line; it will be cut where the page ends.",
"severity": "warning",
"params": {
"word": "x"
}
}
],
"tier": "pay",
"fields": [
"employer.legal_name",
"person.full_name"
],
"law": [
{
"country": "PT",
"reviewed": false,
"covered": [
{
"id": "parties.person",
"label": "The employee's identity",
"required": true,
"source": {
"url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
"article": "Código do Trabalho, art. 141"
},
"confidence": "verified",
"note": null
}
],
"missing": [
{
"id": "reason_for_term",
"label": "The reason for the fixed term",
"required": true,
"source": {
"url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
"article": "Código do Trabalho, art. 141"
},
"confidence": "verified",
"note": "Name the specific facts that justify the term."
}
],
"optional": [],
"manual": [],
"signature": {
"min_level": "qualified",
"who": [
"employer",
"person"
],
"note": "Written form: both sign with a qualified electronic signature or print and sign by hand.",
"source": {
"url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
"article": "Código do Trabalho, art. 141"
},
"confidence": "verified",
"alternatives": [
"print"
]
},
"delivery": {
"deadline": "days_after_start",
"proof_required": true,
"source": {
"url": "https://diariodarepublica.pt/dr/legislacao-consolidada/lei/2009-34546475",
"article": "Código do Trabalho, art. 141"
}
},
"language": {
"mandatory": null,
"default": "pt",
"translation_allowed": true
},
"due": [
{
"part": "all",
"due": "2026-11-09"
}
],
"disclaimer": "Bizisy checks the legal minimum it knows of. It is a starting point, not legal advice: have your templates checked."
}
]
}
}Get the document template settings#
POST/v1/documents/templates.settings.getRead
The company's document template settings (Settings → Documents → Templates): who must approve a new version of a template before it is published — none (the default: publishing is immediate), hr (an owner, admin or HR member other than whoever asks) or owner (an owner; an owner's own version is published at once), with how many logins could approve — and the default document style (style: international or continental; null = each document takes its country's). Owners, admins and HR (and custom roles with Documents at Edit).
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_templates_settings_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
approval"none" | "hr" | "owner"requiredWho approves a new version before it is published: none (publishing is immediate; the default), hr (another owner, admin or HR member than whoever asks), owner (an owner; owners publish their own at once).
approversintegerrequiredHow many logins could approve under the current rule (besides whoever asks).
style"international" | "continental"requiredThe company's default document style: international (1. / 1.1 / (a)) or continental (Cláusula 1.ª / 1 – / a)). null: each document takes its country's (Portugal, Spain, France and Italy continental; every other country international). A template's own default, or a style chosen when generating, wins.
updated_atstring | nullrequiredcan_changebooleanrequiredOwners and admins change it, in the web app.
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/templates.settings.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/documents/templates.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/documents/templates.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": {
"approval": "hr",
"approvers": 3,
"style": null,
"updated_at": "2026-10-19T10:00:00.000Z",
"can_change": true
}
}Change the document template settings#
POST/v1/documents/templates.settings.updateWrite
Changes the company's document template settings (send one or both). approval: who must approve a new version of a template before it is published — none, hr (an owner, admin or HR member other than whoever asks; needs at least two of them) or owner (an owner; owners publish their own at once); requests already waiting keep their approvers. style: the company's default document style, international (1. / 1.1 / (a), "clause 3.2(a)") or continental (Cláusula 1.ª / 1 – / a), "alínea a) do n.º 2 da cláusula 3.ª"), labels in each document's language; null goes back to each country's (Portugal, Spain, France and Italy continental; every other country international). A template's own default and a style chosen when generating win over it; documents already made keep theirs. Owners and admins only, signed in to Bizisy: never over an API key or an AI assistant, so an assistant can never switch approval off.
- Web app only
- Refused for API keys and connected apps. Who approves templates is set by owners and admins in the app.
- MCP tool
documents_templates_settings_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
approval"none" | "hr" | "owner"style"international" | "continental"The default document style; null: each country's.
Returns
approval"none" | "hr" | "owner"requiredWho approves a new version before it is published: none (publishing is immediate; the default), hr (another owner, admin or HR member than whoever asks), owner (an owner; owners publish their own at once).
approversintegerrequiredHow many logins could approve under the current rule (besides whoever asks).
style"international" | "continental"requiredThe company's default document style: international (1. / 1.1 / (a)) or continental (Cláusula 1.ª / 1 – / a)). null: each document takes its country's (Portugal, Spain, France and Italy continental; every other country international). A template's own default, or a style chosen when generating, wins.
updated_atstring | nullrequiredcan_changebooleanrequiredOwners and admins change it, in the web app.
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/templates.settings.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"approval":"owner","style":null}'const res = await fetch('https://api.bizisy.com/v1/documents/templates.settings.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"approval": "owner",
"style": null
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/documents/templates.settings.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"approval": "owner",
"style": None,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"approval": "owner",
"approvers": 3,
"style": null,
"updated_at": "2026-10-19T10:00:00.000Z",
"can_change": true
}
}Approve or send back a template#
POST/v1/documents/templates.decideWrite
Decides a template version waiting for approval (documents_templates_approvals lists them, with what changed): approve publishes it as the next version (documents made from now on use it); reject sends it back to its author with an optional comment (the draft stays as it is). Only an approver by the company's rule (hr: an owner, admin or HR member; owner: an owner), never whoever asked or changed the draft last, signed in to Bizisy: refused over an API key or AI assistant.
- Web app only
- Refused for API keys and connected apps. A person approves template versions in the app (Approvals).
- MCP tool
documents_templates_decideon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
template_idstringrequireddecision"approve" | "reject"requiredcommentstringUp to 500 characters.
Returns
template_idstringrequireddecision"approve" | "reject"requiredversioninteger | nullrequiredThe version published (approve).
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/templates.decide \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"template_id":"tpl1","decision":"reject","comment":"Keep 90 days."}'const res = await fetch('https://api.bizisy.com/v1/documents/templates.decide', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"template_id": "tpl1",
"decision": "reject",
"comment": "Keep 90 days."
}),
});
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/documents/templates.decide",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"template_id": "tpl1",
"decision": "reject",
"comment": "Keep 90 days.",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"template_id": "tpl1",
"decision": "reject",
"version": 3
}
}Withdraw a template from approval#
POST/v1/documents/templates.withdrawWrite
Takes back a template version waiting for approval (or clears a sent-back request), so its draft can change again; nothing is published. Same callers as documents_templates_publish.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_templates_withdrawon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
template_idstringrequired
Returns
template_idstringrequiredwithdrawnbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/templates.withdraw \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"template_id":"tpl1"}'const res = await fetch('https://api.bizisy.com/v1/documents/templates.withdraw', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"template_id": "tpl1"
}),
});
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/documents/templates.withdraw",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"template_id": "tpl1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"template_id": "tpl1",
"withdrawn": true
}
}List templates waiting for approval#
POST/v1/documents/templates.approvalsRead
Template versions waiting for approval, oldest first: the template, the version it makes, who asked and when, whether you may decide it (and why not), and what changed since the last published version (per language: the title, the body line by line, and other settings such as countries or signers). Templates with pay details show what changed only to those who see pay. Owners, admins and HR (and custom roles with Documents at Edit, to see them).
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_templates_approvalson HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
template_idstring
Returns
approvalsobject[]required14 fields
template_idstringrequirednamestringrequiredkindstringrequiredversionintegerrequiredtier"public" | "job" | "private" | "pay"requiredasked_atstringrequiredasked_byobject | nullrequired2 fields
idstringrequirednamestringrequired
approvers"hr" | "owner"requiredcan_decidebooleanrequiredwhy_not"machine" | "yours" | "role" | "decided"requiredWhy you can't decide it: you asked or changed it (yours), your role, or an API key / AI assistant (machine).
previous_versioninteger | nullrequiredbody_hiddenbooleanrequiredIt uses pay details you can't see: what changed is not shown.
changesobject[]required7 fields
language"en" | "pt" | "es" | "fr" | "de" | "it"requiredstatus"changed" | "added" | "removed" | "same"requiredadded: a new language; removed: a language taken out.
titleobject | nullrequiredWhen the title changed.
2 fields
beforestring | nullrequiredafterstring | nullrequired
linesobject[]requiredThe body, line by line: same, add, del; skip folds unchanged lines.
4 fields (one of several shapes)
Option 1
op"same" | "add" | "del"requiredtextstringrequired
Option 2
op"skip"requiredcountintegerrequired
addedintegerrequiredremovedintegerrequiredtoo_longbooleanrequired
details_changedstring[]requiredOther settings that change: name, category, countries, signers, visibility, slots, style.
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/templates.approvals \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"template_id":"tpl1"}'const res = await fetch('https://api.bizisy.com/v1/documents/templates.approvals', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"template_id": "tpl1"
}),
});
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/documents/templates.approvals",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"template_id": "tpl1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"approvals": [
{
"template_id": "tpl1",
"name": "Fixed-term contract (PT)",
"kind": "contract_fixed",
"version": 3,
"tier": "pay",
"asked_at": "2026-10-19T10:00:00.000Z",
"asked_by": {
"id": "u2",
"name": "Helena Costa"
},
"approvers": "hr",
"can_decide": true,
"why_not": null,
"previous_version": 2,
"body_hidden": false,
"changes": [
{
"language": "pt",
"status": "changed",
"title": null,
"added": 1,
"removed": 1,
"too_long": false,
"lines": [
{
"op": "skip",
"count": 4
},
{
"op": "same",
"text": "Cláusula 3.ª"
},
{
"op": "del",
"text": "O período experimental é de 90 dias."
},
{
"op": "add",
"text": "O período experimental é de 60 dias."
},
{
"op": "skip",
"count": 12
}
]
}
],
"details_changed": [
"countries"
]
}
]
}
}Start importing a Word file#
POST/v1/documents/templates.import_startWrite
Step 1 of 2 to make a draft template (documents_templates_import_docx) or clause (documents_clauses_import_docx) from a Word file: send its name, size (at most 5 MB), content_type (application/vnd.openxmlformats-officedocument.wordprocessingml.document) and sha256 (lowercase hex). PUT the bytes to upload.url with exactly upload.headers within 15 minutes, then call step 2 with the file_id (first with dry_run to see the converted text and the suggested fields). The file is checked by its bytes; Word files with macros are refused. It is never kept: deleted once the draft is made, or within two hours when it is not imported. Owners, admins and HR (and custom roles with Documents at Edit).
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_templates_import_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
namestringrequired1–200 characters.
sizeintegerrequiredFrom 0 to 5000000.
content_type"application/vnd.openxmlformats-officedocument.wordprocessingml.document"requiredA Word document (.docx); .doc, .docm, PDF and others are refused.
sha256stringrequiredPattern
^[0-9a-f]{64}$.
Returns
file_idstringrequireduploadobject | nullrequirednull on a dry run.
4 fields
urlstringrequiredmethod"PUT"requiredheadersobjectrequiredresumablefalserequired
expires_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/templates.import_start \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"name": "Contract.docx",
"size": 48000,
"content_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}'const res = await fetch('https://api.bizisy.com/v1/documents/templates.import_start', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"name": "Contract.docx",
"size": 48000,
"content_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"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/documents/templates.import_start",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"name": "Contract.docx",
"size": 48000,
"content_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"file_id": "f1",
"upload": {
"url": "https://storage.example/upload/f1",
"method": "PUT",
"headers": {
"content-type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
},
"resumable": false
},
"expires_at": "2026-10-19T10:15:00.000Z"
}
}Import a Word file as a template#
POST/v1/documents/templates.import_docxWrite
Step 2 (after documents_templates_import_start): converts the uploaded Word file into a draft template's text in one language: headings, paragraphs, bulleted and numbered lists, tables, bold and italic, page breaks (images, comments, footnotes, headers and footers are left out and listed in warnings; tracked changes are accepted). Placeholders it finds become candidates ([Name], [[…]], «…», {{…}}, <<…>>, ____ blanks, highlighted text, mail-merge fields), each with suggested fields matched by its words in that language. Run it with dry_run first: it returns the text, the original's paragraphs, the candidates and their suggestions and creates nothing. Then run it with mappings (candidate id → field, or null to keep it as text): it creates the draft (as documents_templates_create does: lint errors refuse it, at most 300 templates) and deletes the file. Refused: not a .docx, larger than 5 MB, with macros, password-protected, linked to outside content, damaged, or longer than a template (60,000 characters). Same callers as documents_templates_create (API keys and AI assistants: no pay fields).
- Who can call it
- Manage key owner admin hr
- Keys and apps
- No pay fields in the draft it makes.
- MCP tool
documents_templates_import_docxon 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
file_idstringrequired1–64 characters.
language"en" | "pt" | "es" | "fr" | "de" | "it"requiredThe language the document is written in.
kindstring (enum)requiredOne of:
contract_open,contract_fixed,contract_part_time,statement,amendment,change_notice,end_notice,certificate,declaration,policy,letter,offer_letter,pay_review_letter.namestringDefault: the title found in the file.
1–120 characters.
categorystringDefault: Other (Offer letter for an offer letter).
1–40 characters.
countriesstring[]1–30 items. Pattern
^([A-Z]{2}|\*)$.letter_kind"permanent" | "fixed_term"Offer letters only.
mappingsobjectCandidate id → the field it becomes (e.g. {"c1": "person.full_name"}); null or left out: kept as text.
Returns
conversionobjectrequired7 fields
textstringrequiredThe converted text (Markdown-lite), with the mappings applied.
titlestringrequiredThe title found (the first heading or line).
originalstring[]requiredThe Word file's paragraphs as plain text, to compare side by side.
candidatesobject[]required8 fields
idstringrequiredSend it back in mappings with the field it should become.
kindstring (enum)requiredHow it was marked in Word: merge_field, highlight, double_square [[…]], square […], guillemets «…», braces {{…}} (shown as {…}), angle <<…>>, blank ____.
One of:
merge_field,highlight,double_square,square,guillemets,braces,angle,blank.rawstringrequiredAs it appears in the converted text.
labelstringrequiredThe words it carries (for a blank: the words before it); may be empty.
countintegerrequiredHow many times it appears.
contextstringrequiredThe line around its first appearance.
suggestionsobject[]requiredFields it may be, best first (none: no field matched; keep it as text or pick one).
2 fields
pathstringrequiredscorenumberrequired0–1: how well the label matches the field's usual names.
mappedstring | nullrequiredThe field it became (real run) or will become (dry run with mappings); null: kept as text.
warningsobject[]requiredWhat was not imported (images, comments, footnotes, headers and footers, tracked changes accepted…).
2 fields
codestringrequiredmessagestringrequiredEnglish; the app translates it by code.
statsobjectrequired5 fields
paragraphsintegerrequiredheadingsintegerrequiredlistsintegerrequiredtablesintegerrequiredpage_breaksintegerrequired
problemsobject[]requiredLint of the result in that language: errors refuse creating the draft.
8 fields
language"en" | "pt" | "es" | "fr" | "de" | "it"requiredfield"title" | "body"requiredlineintegerrequiredcolintegerrequiredcodestringrequiredmessagestringrequiredEnglish; the app translates by code.
severity"error" | "warning"requiredparamsobject
template_idstring | nullrequiredThe draft made (null on a dry run).
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/templates.import_docx \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"file_id": "f1",
"language": "pt",
"kind": "offer_letter",
"letter_kind": "permanent",
"name": "Carta de oferta",
"category": "Offer letter",
"countries": [
"PT"
],
"mappings": {
"c1": "offer.candidate_name",
"c2": null
}
}'const res = await fetch('https://api.bizisy.com/v1/documents/templates.import_docx', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"file_id": "f1",
"language": "pt",
"kind": "offer_letter",
"letter_kind": "permanent",
"name": "Carta de oferta",
"category": "Offer letter",
"countries": [
"PT"
],
"mappings": {
"c1": "offer.candidate_name",
"c2": null
}
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/documents/templates.import_docx",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"file_id": "f1",
"language": "pt",
"kind": "offer_letter",
"letter_kind": "permanent",
"name": "Carta de oferta",
"category": "Offer letter",
"countries": [
"PT",
],
"mappings": {
"c1": "offer.candidate_name",
"c2": None,
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"conversion": {
"text": "# Employment contract\n\nBetween Acme Lda and {{person.full_name}}, living at [Address].\n\nStart date: {{job.start}}\n",
"title": "Employment contract",
"original": [
"Employment contract",
"Between Acme Lda and [Employee name], living at [Address].",
"Start date: ________"
],
"candidates": [
{
"id": "c1",
"kind": "square",
"raw": "[Employee name]",
"label": "Employee name",
"count": 1,
"context": "Between Acme Lda and [Employee name], living at [Address].",
"suggestions": [
{
"path": "person.full_name",
"score": 1
}
],
"mapped": "person.full_name"
},
{
"id": "c2",
"kind": "square",
"raw": "[Address]",
"label": "Address",
"count": 1,
"context": "Between Acme Lda and [Employee name], living at [Address].",
"suggestions": [
{
"path": "person.address",
"score": 1
},
{
"path": "employer.address",
"score": 0.6
}
],
"mapped": null
},
{
"id": "c3",
"kind": "blank",
"raw": "________",
"label": "Start date",
"count": 1,
"context": "Start date: ________",
"suggestions": [
{
"path": "job.start",
"score": 1
}
],
"mapped": "job.start"
}
],
"warnings": [
{
"code": "images_dropped",
"message": "Pictures were left out."
}
],
"stats": {
"paragraphs": 2,
"headings": 1,
"lists": 0,
"tables": 0,
"page_breaks": 0
},
"problems": []
},
"template_id": "tpl9"
}
}Import a Word file as a clause#
POST/v1/documents/clauses.import_docxWrite
Step 2 (after documents_templates_import_start) for a clause: converts the uploaded Word file into a draft clause of a clause type and a country's rules, in one language (headings become bold lines: a clause's title is its heading). Placeholders become candidates with suggested fields (the clause's typed fields, clause.<field>, and document fields without pay or private details). Dry run first (text, candidates, suggestions; nothing created), then with mappings: it creates the draft clause (as documents_clauses_create does) and deletes the file. At most 8,000 characters. Same refusals as documents_templates_import_docx. Owners, admins and HR, in the web app.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_clauses_import_docxon 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
file_idstringrequired1–64 characters.
language"en" | "pt" | "es" | "fr" | "de" | "it"requiredtypestring (enum)requiredOne of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months.countrystringrequiredPattern
^[A-Z]{2}$.namestring1–120 characters.
mappingsobjectCandidate id → the field it becomes (e.g. {"c1": "person.full_name"}); null or left out: kept as text.
Returns
conversionobjectrequired7 fields
textstringrequiredThe converted text (Markdown-lite), with the mappings applied.
titlestringrequiredThe title found (the first heading or line).
originalstring[]requiredThe Word file's paragraphs as plain text, to compare side by side.
candidatesobject[]required8 fields
idstringrequiredSend it back in mappings with the field it should become.
kindstring (enum)requiredHow it was marked in Word: merge_field, highlight, double_square [[…]], square […], guillemets «…», braces {{…}} (shown as {…}), angle <<…>>, blank ____.
One of:
merge_field,highlight,double_square,square,guillemets,braces,angle,blank.rawstringrequiredAs it appears in the converted text.
labelstringrequiredThe words it carries (for a blank: the words before it); may be empty.
countintegerrequiredHow many times it appears.
contextstringrequiredThe line around its first appearance.
suggestionsobject[]requiredFields it may be, best first (none: no field matched; keep it as text or pick one).
2 fields
pathstringrequiredscorenumberrequired0–1: how well the label matches the field's usual names.
mappedstring | nullrequiredThe field it became (real run) or will become (dry run with mappings); null: kept as text.
warningsobject[]requiredWhat was not imported (images, comments, footnotes, headers and footers, tracked changes accepted…).
2 fields
codestringrequiredmessagestringrequiredEnglish; the app translates it by code.
statsobjectrequired5 fields
paragraphsintegerrequiredheadingsintegerrequiredlistsintegerrequiredtablesintegerrequiredpage_breaksintegerrequired
problemsobject[]requiredLint of the result in that language: errors refuse creating the draft.
8 fields
language"en" | "pt" | "es" | "fr" | "de" | "it"requiredfield"title" | "body"requiredlineintegerrequiredcolintegerrequiredcodestringrequiredmessagestringrequiredEnglish; the app translates by code.
severity"error" | "warning"requiredparamsobject
clause_idstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/clauses.import_docx \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"file_id": "f1",
"language": "pt",
"type": "non_compete",
"country": "DE",
"name": "Wettbewerbsverbot",
"mappings": {
"c1": "clause.duration_months"
}
}'const res = await fetch('https://api.bizisy.com/v1/documents/clauses.import_docx', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"file_id": "f1",
"language": "pt",
"type": "non_compete",
"country": "DE",
"name": "Wettbewerbsverbot",
"mappings": {
"c1": "clause.duration_months"
}
}),
});
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/documents/clauses.import_docx",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"file_id": "f1",
"language": "pt",
"type": "non_compete",
"country": "DE",
"name": "Wettbewerbsverbot",
"mappings": {
"c1": "clause.duration_months",
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"conversion": {
"text": "# Employment contract\n\nBetween Acme Lda and {{person.full_name}}, living at [Address].\n\nStart date: {{job.start}}\n",
"title": "Employment contract",
"original": [
"Employment contract",
"Between Acme Lda and [Employee name], living at [Address].",
"Start date: ________"
],
"candidates": [
{
"id": "c1",
"kind": "square",
"raw": "[Employee name]",
"label": "Employee name",
"count": 1,
"context": "Between Acme Lda and [Employee name], living at [Address].",
"suggestions": [
{
"path": "person.full_name",
"score": 1
}
],
"mapped": "person.full_name"
},
{
"id": "c2",
"kind": "square",
"raw": "[Address]",
"label": "Address",
"count": 1,
"context": "Between Acme Lda and [Employee name], living at [Address].",
"suggestions": [
{
"path": "person.address",
"score": 1
},
{
"path": "employer.address",
"score": 0.6
}
],
"mapped": null
},
{
"id": "c3",
"kind": "blank",
"raw": "________",
"label": "Start date",
"count": 1,
"context": "Start date: ________",
"suggestions": [
{
"path": "job.start",
"score": 1
}
],
"mapped": "job.start"
}
],
"warnings": [
{
"code": "images_dropped",
"message": "Pictures were left out."
}
],
"stats": {
"paragraphs": 2,
"headings": 1,
"lists": 0,
"tables": 0,
"page_breaks": 0
},
"problems": []
},
"clause_id": null
}
}Generate documents from a template#
POST/v1/documents/generateWrite
Makes a PDF document from a published template (or a built-in) for each person: person_ids (1–200) or group_id (a saved group, expanded on the server). version: default the latest; language: default each person's country's language, else your company's, else English (en, pt, es, fr, de, it, as the template has them). Use dry_run first: it returns, per person, missing (fields with no value: nothing is generated with a silent blank), dropped (lines left out because all their fields are empty), withheld (fields you may not see for that person), the law's minimum signature level for their country, and previews (HTML) for the first 20. overrides: { <person_id>: { <field path>: value } } for this document only (e.g. a reason for a fixed term). The real run is refused while anyone has missing or withheld fields; it files each PDF in Documents (the template's category and visibility, with the template and version it came from) and, with send ({ method: tool (your e-signature tool, the default) bizisy_accept (Bizisy click-to-accept, a simple signature, only where the law accepts one) or autenticacao_gov (companies in Portugal: a qualified signature made in Autenticação.gov, each signed PDF uploaded back), level, reminders, expires_on }), sends each for signature to the template's signers. style: how clauses, paragraphs and items are numbered and cited, with labels in the document's language: international (1. / 1.1 / (a), "clause 3.2(a)") or continental (Cláusula 1.ª / 1 – / a), "alínea a) do n.º 2 da cláusula 3.ª"). Precedence: the style given here, else the template's default style, else the company's (documents_templates_settings_update), else the country's (Portugal, Spain, France and Italy continental; every other country international). The style applies to everyone in the call (dry run included) and is recorded on each document (generated_from.style), so its Word copy matches. Limits: 200 people a call, 2000 documents a company a day. Owners, admins and HR (and custom roles with Documents at Edit, for the people they cover; a template with pay details only for those who see pay). API keys and AI assistants may generate only templates without private or pay details. The law check is a starting point, not legal advice.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Only templates without private or pay details.
- MCP tool
documents_generateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity
Input
template_idstringrequiredversionintegerAt least 1.
language"en" | "pt" | "es" | "fr" | "de" | "it"person_idsstring[]1–200 items.
group_idstringoverridesobjectclausesobjectThe clauses (D10): per slot the clauses in order with their typed fields; fixed clauses' fields; per_person overrides. Default: each slot's defaults. Each person's country picks the variant and its rules: a blocked clause keeps that person's document from being made.
3 fields
slotsobjectPer clause slot, the clauses in order (an empty list: none). A slot left out gets its defaults.
fixedobjectFixed clauses ({{clause "type"}}): their typed fields, or another clause of that type.
16 fields
non_competeobjectrequired2 fields
clause_idstring1–100 characters.
fieldsobject
non_solicitationobjectrequired2 fields
clause_idstring1–100 characters.
fieldsobject
probationobjectrequired2 fields
clause_idstring1–100 characters.
fieldsobject
training_repaymentobjectrequired2 fields
clause_idstring1–100 characters.
fieldsobject
remote_workobjectrequired2 fields
clause_idstring1–100 characters.
fieldsobject
exclusivityobjectrequired2 fields
clause_idstring1–100 characters.
fieldsobject
confidentialityobjectrequired2 fields
clause_idstring1–100 characters.
fieldsobject
ip_inventionsobjectrequired2 fields
clause_idstring1–100 characters.
fieldsobject
mobilityobjectrequired2 fields
clause_idstring1–100 characters.
fieldsobject
overtime_includedobjectrequired2 fields
clause_idstring1–100 characters.
fieldsobject
noticeobjectrequired2 fields
clause_idstring1–100 characters.
fieldsobject
garden_leaveobjectrequired2 fields
clause_idstring1–100 characters.
fieldsobject
equipmentobjectrequired2 fields
clause_idstring1–100 characters.
fieldsobject
monitoring_noticeobjectrequired2 fields
clause_idstring1–100 characters.
fieldsobject
collective_agreementobjectrequired2 fields
clause_idstring1–100 characters.
fieldsobject
pay_extra_monthsobjectrequired2 fields
clause_idstring1–100 characters.
fieldsobject
per_personobjectPer person_id, slots or fixed clauses that differ from the batch's choice (a slot given here replaces the batch's for that person).
style"international" | "continental"The document style for everyone in this call: international or continental. Default per person: the template's, else the company's, else their country's.
draftbooleanDefault true unless send is given: each document is a draft only HR sees, until you send it to the person (
documents_prepared_decide). false: the person sees it at once (the template's visibility).bulk_run_idstringInternal: the background run this call is a step of (set by Bizisy, never by you).
sendobject4 fields
method"tool" | "autenticacao_gov" | "bizisy_accept"level"simple" | "advanced" | "qualified"remindersobject | null2 fields
interval_days1 | 2 | 7 | 14requiredmaxintegerrequiredFrom 1 to 10.
expires_onstringPattern
^\d{4}-\d{2}-\d{2}$.
Returns
7 fields
template_idstringrequiredversionintegerrequiredpeopleobject[]required15 fields
person_idstringrequirednamestring | nullrequiredThe person's name (null when not found).
language"en" | "pt" | "es" | "fr" | "de" | "it"requiredreadybooleanrequiredNothing missing or withheld: a real run makes this person's document.
missingstring[]requiredFields with no value on lines that stay: fill them on the profile, or pass overrides for this document only.
droppedstring[]requiredLines left out because all their fields are empty.
withheldstring[]requiredFields you may not see for this person: you can't generate this template for them.
problemstring | nullrequiredWhy this person can't get the document (not found, a field withheld).
style"international" | "continental"requiredThe document style their document is made in (the one chosen, else the template's, the company's, their country's).
lawobject | nullrequired6 fields
countrystringrequiredmin_level"none" | "simple" | "advanced" | "qualified" | "wet"requiredThe lowest signature level the law accepts for this document in their country.
level_okboolean | nullrequiredWith send: the level it would be sent with meets it (null without send).
blockingbooleanrequiredA verified rule: sending below it is refused.
notestring | nullrequiredraised_by_clausebooleanA clause in it needs a higher level than the document itself (e.g. a German non-compete).
clausesobject[]The clauses in this person's document: the variant of their country, the rules' result (a block keeps the document from being made), warnings, the law note and the signature level a clause needs.
18 fields
okbooleanrequiredNo block: the clause may go in the document.
countrystring (enum)requiredWhose rules ran: PT, ES, FR, DE, IT, NL, or EU (the EU minimum, for any other country).
One of:
PT,ES,FR,DE,IT,NL,EU.blocksobject[]requiredThe law Bizisy treats as settled is broken: the document is refused with it.
6 fields
rulestringrequiredmessagestringrequiredEnglish with {params}; the app translates it.
paramsobject | nullrequiredfieldstring | nullrequiredThe typed field it is about.
sourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"required
warnsobject[]requiredLess certain rules and reminders: the document is made, check with your lawyer.
6 fields
rulestringrequiredmessagestringrequiredEnglish with {params}; the app translates it.
paramsobject | nullrequiredfieldstring | nullrequiredThe typed field it is about.
sourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"required
raises_toobject | nullrequiredThe signature level the clause needs (e.g. a German non-compete: qualified or by hand).
3 fields
level"none" | "simple" | "advanced" | "qualified" | "wet"requiredconfidence"verified" | "medium" | "uncertain"requiredsourceobject | nullrequired2 fields
urlstringrequiredarticlestringrequired
tasksobject[]requiredTo do once signed (Italy: file the smart-working agreement within 5 days).
4 fields
idstringrequiredlabelstringrequireddays_after_startintegerrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
fieldsobjectrequiredThe fields as checked (defaults filled in).
slotstring | nullrequiredThe slot it is in (null: a fixed clause).
typestring (enum)requiredOne of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months.clause_idstringrequiredsource"builtin" | "company"requiredversionintegerrequirednamestringrequiredvariant_countrystring (enum)requiredWhose rules ran: the person's country, or EU.
One of:
PT,ES,FR,DE,IT,NL,EU.notestringrequiredWhat the law says there (English; the app translates it).
confidence"verified" | "medium" | "uncertain"requiredsourcesobject[]required2 fields
urlstringrequiredarticlestringrequired
other_countrybooleanrequiredYour clause was written for another country's rules; it still runs the person's.
preview_htmlstring | nullrequiredDry runs: the document as HTML for the first 20 people (
documents_templates_previewfor the rest).document_idstring | nullrequiredsignature_idstring | nullrequiredprepared_idstring | nullA draft (HR only until sent): send, edit or discard it with
documents_prepared_decide.
createdintegerrequiredsentintegerrequiredrunobject | nullMore than 20 people: the documents are made in the background; follow it with
documents_generate_run_get.3 fields
idstringrequiredstatus"working" | "done" | "failed" | "cancelled"requiredtotalintegerrequired
today_leftintegerrequiredDocuments your company may still generate today (2000 a day for a company of up to that many people; one a day per person above that).
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/generate \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"template_id": "tpl1",
"person_ids": [
"p1",
"p2"
],
"clauses": {
"slots": {
"optional": [
{
"type": "non_compete",
"clause_id": "cl1",
"fields": {
"compensation_pct": 50,
"geography": "Germany"
}
}
]
},
"per_person": {
"p2": {
"slots": {
"optional": []
}
}
}
}
}'const res = await fetch('https://api.bizisy.com/v1/documents/generate', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"template_id": "tpl1",
"person_ids": [
"p1",
"p2"
],
"clauses": {
"slots": {
"optional": [
{
"type": "non_compete",
"clause_id": "cl1",
"fields": {
"compensation_pct": 50,
"geography": "Germany"
}
}
]
},
"per_person": {
"p2": {
"slots": {
"optional": []
}
}
}
}
}),
});
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/documents/generate",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"template_id": "tpl1",
"person_ids": [
"p1",
"p2",
],
"clauses": {
"slots": {
"optional": [
{
"type": "non_compete",
"clause_id": "cl1",
"fields": {
"compensation_pct": 50,
"geography": "Germany",
},
},
],
},
"per_person": {
"p2": {
"slots": {
"optional": [],
},
},
},
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"template_id": "tpl1",
"version": 2,
"people": [
{
"person_id": "p1",
"name": "Ana Ferreira",
"language": "pt",
"ready": true,
"missing": [],
"dropped": [],
"withheld": [],
"problem": null,
"style": "continental",
"law": {
"country": "PT",
"min_level": "qualified",
"level_ok": null,
"blocking": true,
"note": null,
"raised_by_clause": false
},
"preview_html": null,
"document_id": "d20",
"signature_id": null,
"clauses": [
{
"ok": true,
"country": "DE",
"blocks": [],
"warns": [],
"raises_to": {
"level": "qualified",
"confidence": "verified",
"source": {
"url": "https://www.gesetze-im-internet.de/bgb/__126a.html",
"article": "HGB §74 Abs. 1; BGB §§126, 126a"
}
},
"tasks": [],
"fields": {
"duration_months": 12,
"compensation_pct": 50,
"waiver": "none"
},
"slot": "optional",
"type": "non_compete",
"clause_id": "builtin:clause.de.non_compete",
"source": "builtin",
"version": 1,
"name": "Non-compete after leaving (Germany)",
"variant_country": "DE",
"note": "Written and signed, with the signed document handed over; at least 50% of the last total pay, monthly, for up to 2 years; never with a minor.",
"confidence": "medium",
"sources": [
{
"url": "https://www.gesetze-im-internet.de/hgb/__74.html",
"article": "HGB §74 Abs. 1 und 2"
}
],
"other_country": false
}
]
}
],
"created": 1,
"sent": 0,
"today_left": 1999
}
}List documents made from templates#
POST/v1/documents/generated.listRead
Documents made from templates, newest first: of one template (template_id, optionally version: who has which version), of one person (person_id), with a clause (clause_type; clause_id, optionally clause_version: who has which wording), or all; each with its template, version, language, its clauses and its latest signature request (signed or not). Only documents you can see; through an API key or an AI assistant, other people's documents come as metadata only. Owners, admins and HR (and custom roles with Documents at Edit).
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Other people's documents come as metadata only.
- MCP tool
documents_generated_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
template_idstringversionintegerAt least 1.
person_idstringclause_typestring (enum)One of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months.clause_idstringclause_versionintegerWith clause_id.
At least 1.
limitintegerDefault 200.
From 1 to 500.
Returns
documentsobject[]required9 fields
documentobjectrequired19 fields
idstringrequiredtitlestringrequiredcategorystringrequiredsubjectobjectrequired3 fields (one of several shapes)
Option 1
kind"person"requiredpersonobject | nullrequired2 fields
idstringrequirednamestringrequired
Option 2
kind"company"required
visibilitystring (enum)requiredOne of:
hr,hr_person,hr_person_manager,everyone,managers,hr,accountant.uploaded_by"hr" | "self"requiredself: the person added it themself ("From me", or a custom field they fill in).
fieldobject | nullrequiredA custom file field's file (
org_fields_list): its visibility follows the field's tier; replace or remove it through the field.2 fields
keystringrequiredlabelstringrequired
expires_onstring | nullrequirednotesstring | nullrequirednull when you only see metadata.
fileobjectrequired4 fields
namestring | nullrequiredThe original file name; null when you only see metadata.
sizeintegerrequiredcontent_typestringrequiredpreviewablebooleanrequiredThe web app can show it (PDF, PNG, JPEG, WebP).
access"full" | "metadata"requiredmetadata: title, category, date and size only (no notes, no download): API keys and AI assistants never get the contents of other people's documents.
signed_fromobject | nullrequiredA signed copy or signature audit trail the e-signature tool handed back: the original document. null for other documents.
2 fields
document_idstringrequiredkind"signed" | "audit_trail"required
signatureobject | nullThe latest signature request (lists only): status, level and how many have signed.
6 fields
idstringrequiredstatusstring (enum)requiredOne of:
queued,sending,ongoing,done,declined,expired,canceled,failed.level"simple" | "advanced" | "qualified"requiredsignedintegerrequiredtotalintegerrequiredyour_turnbooleanrequiredYou are the signer the e-signature tool is waiting for (check your email from it).
generated_fromobject | nullMade from a document template: which one, its version, language and style (
documents_templates_get). null for uploaded documents.4 fields
template_idstringrequiredversionintegerrequiredlanguagestringrequiredstyle"international" | "continental"requiredThe document style it was made in (international or continental); null for documents made before styles existed.
draftobject | nullA draft only HR sees until it is sent (
documents_prepared_decide): the prepared document, and who will see it once sent. null otherwise.2 fields
prepared_idstringrequiredvisibility"hr" | "hr_person" | "hr_person_manager"required
deliveryobject | nullProof of delivery of a written statement or change notice: when it was sent, first opened and its receipt confirmed (or handed over on paper). null for other documents.
5 fields
method"electronic" | "print"requiredsent_atstringrequiredopened_atstring | nullrequiredacknowledged_atstring | nullrequiredhanded_over_onstring | nullrequired
status"pending" | "ready"requiredcreated_atstringrequiredupdated_atstringrequired
template_idstringrequiredversionintegerrequiredlanguage"en" | "pt" | "es" | "fr" | "de" | "it"requiredkindstring (enum)requiredOne of:
contract_open,contract_fixed,contract_part_time,statement,amendment,change_notice,end_notice,certificate,declaration,policy,letter,offer_letter,pay_review_letter.reasonstring (enum)requiredOne of:
manual,bulk,hire,rehire,change,request,current_staff,fixed_term_end,leaving,pay_review.signatureobject | nullrequired6 fields
idstringrequiredstatusstring (enum)requiredOne of:
queued,sending,ongoing,done,declined,expired,canceled,failed.level"simple" | "advanced" | "qualified"requiredsignedintegerrequiredtotalintegerrequiredyour_turnbooleanrequiredYou are the signer the e-signature tool is waiting for (check your email from it).
clausesobject[]requiredThe clauses in it: type, the country whose rules ran, the clause and its version.
5 fields
slotstring | nullrequiredtypestring (enum)requiredOne of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months.countrystringrequiredclause_idstringrequiredversionintegerrequired
style"international" | "continental"requiredThe document style it was made in (null: made before styles existed).
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/generated.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"clause_id":"cl1","clause_version":2}'const res = await fetch('https://api.bizisy.com/v1/documents/generated.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"clause_id": "cl1",
"clause_version": 2
}),
});
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/documents/generated.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"clause_id": "cl1",
"clause_version": 2,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"documents": [
{
"document": {
"id": "d20",
"title": "Contrato a termo – Ana Ferreira",
"category": "Contract",
"subject": {
"kind": "person",
"person": {
"id": "p1",
"name": "Ana Ferreira"
}
},
"visibility": "hr_person",
"uploaded_by": "hr",
"field": null,
"expires_on": null,
"notes": null,
"file": {
"name": "Contrato a termo – Ana Ferreira.pdf",
"size": 48000,
"content_type": "application/pdf",
"previewable": true
},
"access": "full",
"status": "ready",
"created_at": "2026-10-19T10:00:00.000Z",
"updated_at": "2026-10-19T10:00:00.000Z",
"signed_from": null,
"generated_from": {
"template_id": "tpl1",
"version": 2,
"language": "pt",
"style": "continental"
}
},
"template_id": "tpl1",
"version": 2,
"language": "pt",
"kind": "contract_fixed",
"reason": "manual",
"signature": null,
"clauses": [
{
"slot": "optional",
"type": "non_compete",
"country": "DE",
"clause_id": "cl1",
"version": 2
}
],
"style": "continental"
}
]
}
}Download a document or template as PDF or Word#
POST/v1/documents/exportWrite
A download link (5 minutes) for a document made from a template (document_id) or for a template (template_id; optionally version and language), as pdf or docx (Word: headings, lists, tables, header and page numbers). A generated document's Word copy is made from the same filled text as its PDF (the PDF stays the signed record); a template keeps its {{fields}} as text, for a lawyer to review. Documents: anyone who can open the document (the person for their own); through an API key or an AI assistant, never other people's documents. Templates: owners, admins and HR (one with pay details only for those who see pay, in the web app).
- Who can call it
- Manage key any Manage role
Me key anyone - Keys and apps
- Never other people's documents; no templates with pay details.
- MCP tool
documents_exporton HR Assistant, My Workplace- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
document_idstringtemplate_idstringversionintegerAt least 1.
language"en" | "pt" | "es" | "fr" | "de" | "it"format"pdf" | "docx"required
Returns
urlstring | nullrequiredSigned URL valid for 5 minutes, downloads as an attachment. null on a dry run. Never store or share it.
expires_atstring | nullrequiredfile_namestringrequiredcontent_typestringrequiredsizeintegerrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/export \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"template_id":"tpl1","version":2,"language":"pt","format":"pdf"}'const res = await fetch('https://api.bizisy.com/v1/documents/export', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"template_id": "tpl1",
"version": 2,
"language": "pt",
"format": "pdf"
}),
});
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/documents/export",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"template_id": "tpl1",
"version": 2,
"language": "pt",
"format": "pdf",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"url": "https://storage.example/d20.docx",
"expires_at": "2026-10-19T10:05:00.000Z",
"file_name": "Contrato a termo – Ana Ferreira.docx",
"content_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"size": 12000
}
}Follow a background document generation#
POST/v1/documents/generate.run_getRead
How a generation of many documents is going (documents_generate returns run.id when it makes them in the background, for more than 20 people): working, done, failed or cancelled; how many people are done, documents made, and the people whose document could not be made with why. Owners, admins and HR, and custom roles with Documents at Edit (the runs they started).
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_generate_run_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
run_idstringrequired
Returns
9 fields
idstringrequiredstatus"working" | "done" | "failed" | "cancelled"requiredtotalintegerrequireddoneintegerrequiredcreatedintegerrequiredDocuments made so far.
problemsobject[]requiredPeople whose document could not be made, and why.
2 fields
person_idstringrequiredproblemstringrequired
errorstring | nullrequiredcreated_atstringrequiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/generate.run_get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"run_id":"run1"}'const res = await fetch('https://api.bizisy.com/v1/documents/generate.run_get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"run_id": "run1"
}),
});
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/documents/generate.run_get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"run_id": "run1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "run1",
"status": "working",
"total": 40,
"done": 12,
"created": 12,
"problems": [],
"error": null,
"created_at": "2026-10-20T09:00:00.000Z",
"updated_at": "2026-10-20T09:01:00.000Z"
}
}Stop a background document generation#
POST/v1/documents/generate.run_cancelWrite
Stops a generation of many documents that is still working: the documents already made stay; nobody else gets one. Owners, admins and HR, or whoever started it.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_generate_run_cancelon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
run_idstringrequired
Returns
9 fields
idstringrequiredstatus"working" | "done" | "failed" | "cancelled"requiredtotalintegerrequireddoneintegerrequiredcreatedintegerrequiredDocuments made so far.
problemsobject[]requiredPeople whose document could not be made, and why.
2 fields
person_idstringrequiredproblemstringrequired
errorstring | nullrequiredcreated_atstringrequiredupdated_atstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/generate.run_cancel \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"run_id":"run1"}'const res = await fetch('https://api.bizisy.com/v1/documents/generate.run_cancel', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"run_id": "run1"
}),
});
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/documents/generate.run_cancel",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"run_id": "run1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "run1",
"status": "cancelled",
"total": 40,
"done": 12,
"created": 12,
"problems": [],
"error": null,
"created_at": "2026-10-20T09:00:00.000Z",
"updated_at": "2026-10-20T09:01:00.000Z"
}
}See automatic documents#
POST/v1/documents/automations.getRead
The company's automatic documents (Settings → Documents → Automatic documents): the written statement of working conditions prepared at hire (on by default) and sent by itself on its legal deadline when HR has not acted (on by default), change notices prepared when an approved change of statement items takes effect (always waiting for HR), amendments to the contract for approved changes (off by default), fixed-term contracts (end notice before the end, renewal addendum; on by default), the work certificate on the last day (on by default), what "Ask for my written statement" and "Ask for a document" (employment declaration: to HR by default; salary declaration: off by default) in My workspace do, the template per kind (null: each person's country's built-in), and the German §2a sector. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_automations_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
No input: send {}.
Returns
9 fields
statementobjectrequired3 fields
onbooleanrequiredPrepare the written statement when someone is hired (default on: a legal duty in every EU country).
auto_sendbooleanrequiredSend it by itself on its legal deadline when HR has not acted (default on).
template_idstring | nullrequirednull: the built-in for each person's country.
change_noticeobjectrequired2 fields
onbooleanrequiredPrepare a change notice when an approved change of statement items takes effect (default on; always waits for HR).
template_idstring | nullrequired
self_request"off" | "review" | "instant"requiredMy workspace "Ask for my written statement": off, review (prepared for HR, default) or instant (sent at once).
de_sectorstring | nullrequiredGermany: the company's SchwarzArbG §2a sector, whose statements are printed and signed by hand.
amendmentobjectrequired2 fields
onbooleanrequiredPrepare an amendment (addendum) to the contract when an approved change takes effect (default off; always waits for HR).
template_idstring | nullrequired
fixed_termobjectrequired3 fields
onbooleanrequiredFixed-term contracts (default on): the end notice before the end by the country's deadline (Netherlands one month, BW 7:668; Portugal 15 days, CT art. 344…), and when HR renews one or makes it open-ended, the renewal addendum or the amendment. Always waits for HR.
end_notice_template_idstring | nullrequiredrenewal_template_idstring | nullrequired
certificateobjectrequired2 fields
onbooleanrequiredPrepare the work certificate on the last day where the law gives one then (Portugal, France, Germany, Italy; default on; waits for HR). Never before the person has been told about their leaving.
template_idstring | nullrequired
declarationsobjectrequired4 fields
employment"off" | "review" | "instant"requiredMy workspace "Ask for a document": the employment declaration: off, review (prepared for HR, default) or instant.
salary"off" | "review" | "instant"requiredThe salary declaration (it shows pay): off by default, review or instant.
employment_template_idstring | nullrequiredsalary_template_idstring | nullrequired
sectorsobject[]requiredThe §2a sectors (labels in English; the app translates them).
2 fields
idstringrequiredlabelstringrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/automations.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const res = await fetch('https://api.bizisy.com/v1/documents/automations.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/documents/automations.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": {
"statement": {
"on": true,
"auto_send": true,
"template_id": null
},
"change_notice": {
"on": true,
"template_id": null
},
"self_request": "review",
"de_sector": null,
"amendment": {
"on": false,
"template_id": null
},
"fixed_term": {
"on": true,
"end_notice_template_id": null,
"renewal_template_id": null
},
"certificate": {
"on": true,
"template_id": null
},
"declarations": {
"employment": "review",
"salary": "off",
"employment_template_id": null,
"salary_template_id": null
},
"sectors": [
{
"id": "construction",
"label": "Construction"
}
]
}
}Change automatic documents#
POST/v1/documents/automations.setWrite
Changes the automatic documents: statement {on, auto_send, template_id}, change_notice {on, template_id}, self_request (off, review or instant), de_sector (a §2a SchwarzArbG sector id from documents_automations_get, or null), amendment {on, template_id}, fixed_term {on, end_notice_template_id, renewal_template_id}, certificate {on, template_id}, declarations {employment, salary: off | review | instant, employment_template_id, salary_template_id}. Send only what changes. A template_id must be a published template of that kind (yours or a built-in); null goes back to each person's country's built-in. Turning a switch off prepares nothing new; documents already prepared stay. Owners, admins and HR. Dry run supported.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_automations_seton HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
statementobject3 fields
onbooleanauto_sendbooleantemplate_idstring | null
change_noticeobject2 fields
onbooleantemplate_idstring | null
self_request"off" | "review" | "instant"de_sectorstring | null1–60 characters.
amendmentobject2 fields
onbooleantemplate_idstring | null
fixed_termobject3 fields
onbooleanend_notice_template_idstring | nullrenewal_template_idstring | null
certificateobject2 fields
onbooleantemplate_idstring | null
declarationsobject4 fields
employment"off" | "review" | "instant"salary"off" | "review" | "instant"employment_template_idstring | nullsalary_template_idstring | null
Returns
9 fields
statementobjectrequired3 fields
onbooleanrequiredPrepare the written statement when someone is hired (default on: a legal duty in every EU country).
auto_sendbooleanrequiredSend it by itself on its legal deadline when HR has not acted (default on).
template_idstring | nullrequirednull: the built-in for each person's country.
change_noticeobjectrequired2 fields
onbooleanrequiredPrepare a change notice when an approved change of statement items takes effect (default on; always waits for HR).
template_idstring | nullrequired
self_request"off" | "review" | "instant"requiredMy workspace "Ask for my written statement": off, review (prepared for HR, default) or instant (sent at once).
de_sectorstring | nullrequiredGermany: the company's SchwarzArbG §2a sector, whose statements are printed and signed by hand.
amendmentobjectrequired2 fields
onbooleanrequiredPrepare an amendment (addendum) to the contract when an approved change takes effect (default off; always waits for HR).
template_idstring | nullrequired
fixed_termobjectrequired3 fields
onbooleanrequiredFixed-term contracts (default on): the end notice before the end by the country's deadline (Netherlands one month, BW 7:668; Portugal 15 days, CT art. 344…), and when HR renews one or makes it open-ended, the renewal addendum or the amendment. Always waits for HR.
end_notice_template_idstring | nullrequiredrenewal_template_idstring | nullrequired
certificateobjectrequired2 fields
onbooleanrequiredPrepare the work certificate on the last day where the law gives one then (Portugal, France, Germany, Italy; default on; waits for HR). Never before the person has been told about their leaving.
template_idstring | nullrequired
declarationsobjectrequired4 fields
employment"off" | "review" | "instant"requiredMy workspace "Ask for a document": the employment declaration: off, review (prepared for HR, default) or instant.
salary"off" | "review" | "instant"requiredThe salary declaration (it shows pay): off by default, review or instant.
employment_template_idstring | nullrequiredsalary_template_idstring | nullrequired
sectorsobject[]requiredThe §2a sectors (labels in English; the app translates them).
2 fields
idstringrequiredlabelstringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/automations.set \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"amendment": {
"on": true
},
"fixed_term": {
"renewal_template_id": "tpl10"
},
"certificate": {
"on": false
},
"declarations": {
"salary": "review",
"employment": "instant"
}
}'const res = await fetch('https://api.bizisy.com/v1/documents/automations.set', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"amendment": {
"on": true
},
"fixed_term": {
"renewal_template_id": "tpl10"
},
"certificate": {
"on": false
},
"declarations": {
"salary": "review",
"employment": "instant"
}
}),
});
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/documents/automations.set",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"amendment": {
"on": True,
},
"fixed_term": {
"renewal_template_id": "tpl10",
},
"certificate": {
"on": False,
},
"declarations": {
"salary": "review",
"employment": "instant",
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"statement": {
"on": true,
"auto_send": true,
"template_id": null
},
"change_notice": {
"on": true,
"template_id": null
},
"self_request": "review",
"de_sector": null,
"amendment": {
"on": false,
"template_id": null
},
"fixed_term": {
"on": true,
"end_notice_template_id": null,
"renewal_template_id": null
},
"certificate": {
"on": true,
"template_id": null
},
"declarations": {
"employment": "review",
"salary": "off",
"employment_template_id": null,
"salary_template_id": null
},
"sectors": [
{
"id": "construction",
"label": "Construction"
}
]
}
}See consent to electronic documents#
POST/v1/documents/consent.getRead
Whether a person agreed to receive their documents electronically (in the Netherlands a written statement goes electronically only with this consent, BW 7:655 lid 3), when and who recorded it. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_consent_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
person_idstringrequired
Returns
person_idstringrequiredelectronicbooleanrequiredatstring | nullrequiredby"self" | "hr"required
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/consent.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"person_id":"p1"}'const res = await fetch('https://api.bizisy.com/v1/documents/consent.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"person_id": "p1"
}),
});
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/documents/consent.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"person_id": "p1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"person_id": "p1",
"electronic": false,
"at": null,
"by": null
}
}Record consent to electronic documents#
POST/v1/documents/consent.setWrite
Records that a person agreed (electronic true) or no longer agrees (false) to receive their documents electronically, e.g. on a signed form. Their prepared statements switch between electronic and paper delivery. Owners, admins and HR, in the app; people record their own in My workspace. Dry run supported.
- Web app only
- Refused for API keys and connected apps. Consent to electronic documents is recorded by HR or the person in the app.
- MCP tool
documents_consent_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
person_idstringrequiredelectronicbooleanrequired
Returns
person_idstringrequiredelectronicbooleanrequiredatstring | nullrequiredby"self" | "hr"required
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/consent.set \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"person_id":"p1","electronic":true}'const res = await fetch('https://api.bizisy.com/v1/documents/consent.set', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_id": "p1",
"electronic": 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/documents/consent.set",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p1",
"electronic": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"person_id": "p1",
"electronic": true,
"at": "2026-10-20T09:00:00.000Z",
"by": "hr"
}
}List prepared documents#
POST/v1/documents/prepared.listRead
Documents waiting for HR (status prepared, default; or sent, discarded, all): written statements of working conditions prepared at hire (with their legal deadline per country: due_on, overdue), change notices prepared when an approved change took effect (the fields that changed, never their values), statements people asked for, and drafts made with documents_generate. Each with how it reaches the person (electronic, or print in the Netherlands without consent and in German §2a sectors), why a statement could not go out by itself (blocked), and proof of delivery once sent (sent, opened, confirmed). person_id: one person's. Prepared documents are HR's until sent: the person and their managers see nothing before. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_prepared_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
status"prepared" | "sent" | "discarded" | "all"Default prepared.
person_idstringkindstring (enum)One of:
contract_open,contract_fixed,contract_part_time,statement,amendment,change_notice,end_notice,certificate,declaration,policy,letter,offer_letter,pay_review_letter.limitintegerDefault 200.
From 1 to 500.
Returns
preparedobject[]required22 fields
idstringrequiredpersonobject | nullrequired2 fields
idstringrequirednamestringrequired
kindstring (enum)requiredstatement (written statement of working conditions), change_notice, or the kind of a generated draft.
One of:
contract_open,contract_fixed,contract_part_time,statement,amendment,change_notice,end_notice,certificate,declaration,policy,letter,offer_letter,pay_review_letter.reasonstring (enum)requiredhire, rehire, change (an approved change took effect), request (the person asked), current_staff, manual or bulk (drafts made with
documents_generate).One of:
hire,rehire,change,request,current_staff,manual,bulk,fixed_term_end,leaving,pay_review.status"prepared" | "sent" | "discarded"requireddue_onstring | nullrequiredThe legal deadline to give it to the person (null: none).
overduebooleanrequiredpartsobject[]requiredDeadlines per part (e.g. Germany: day 1, day 7, one month).
2 fields
partstringrequiredduestringrequired
deliveryobjectrequiredelectronic (My workspace, email, receipt to confirm) or print (NL without consent, a DE §2a sector).
2 fields
method"electronic" | "print"requiredwhy"nl_no_consent" | "de_sector" | "chosen" | "no_consent"required
employer_qesbooleanrequiredNL: sent electronically, it must carry the employer's qualified electronic signature: send a signed copy (signed_document_id).
template_idstring | nullrequirednull: the company's choice for the kind, else the country's built-in.
document_idstring | nullrequiredThe document once rendered (HR only until sent).
changed_fieldsstring[]requiredChange notices: the fields that changed (values only in the app, in the document).
effectivestring | nullrequiredChange notices: the day the change takes effect.
blockedobject | nullrequiredWhy it could not go out by itself on its deadline (statements): values missing, it goes on paper, or it needs your qualified signature.
3 fields
onstringrequiredwhystring (enum)requiredclause: a clause in it breaks the law for the person (regenerate it with other clause fields). visibility: its template shares pay or private details with managers. failed: it could not be made (storage full, the PDF); send it again.
One of:
missing,print,no_template,person_gone,qes,clause,visibility,failed.missingstring[]required
sentobject | nullrequiredProof of delivery: when it went, how, when the person first opened it and when they confirmed receipt.
6 fields
atstringrequiredby"hr" | "auto" | "self"requiredmethod"electronic" | "print"requiredhanded_over_onstring | nullrequiredopened_atstring | nullrequiredacknowledged_atstring | nullrequired
discarded_atstring | nullrequiredcreated_atstringrequiredvariant"renewal" | "reference" | "salary" | "employment"requiredStep 4: renewal (an amendment renewing a fixed-term contract), reference (DE qualified reference), salary or employment (declarations); null: the kind's own document.
warningsobject[]requiredWhat to know before sending: unilateral_notice (Spain, art. 41 ET: a substantial change the company decides alone reaches the person `days` days before, by `by`), protected_venue (Italy, art. 2103 c.c.: a downgrade is signed in a protected venue, never by click-to-accept), late (prepared after its legal deadline).
4 fields
code"unilateral_notice" | "protected_venue" | "late"requireddaysinteger | nullrequiredbystring | nullrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
decisionobject | nullrequiredEnd notices: what HR decided for the fixed-term contract (renew until new_end_date, permanent, or end); null until decided (it can't be sent before).
3 fields
outcome"renew" | "permanent" | "end"requirednew_end_datestring | nullrequiredtermsstring | nullrequired
contract_endstring | nullrequiredEnd notices: the contract's end date.
countsobjectrequired3 fields
preparedintegerrequiredoverdueintegerrequireddue_soonintegerrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/prepared.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status":"all","person_id":"p1","kind":"statement","limit":50}'const res = await fetch('https://api.bizisy.com/v1/documents/prepared.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"status": "all",
"person_id": "p1",
"kind": "statement",
"limit": 50
}),
});
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/documents/prepared.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"status": "all",
"person_id": "p1",
"kind": "statement",
"limit": 50,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"prepared": [
{
"id": "prep1",
"person": {
"id": "p1",
"name": "Ana Ferreira"
},
"kind": "statement",
"reason": "hire",
"status": "prepared",
"due_on": "2026-11-09",
"overdue": false,
"parts": [
{
"part": "core",
"due": "2026-11-09"
},
{
"part": "rest",
"due": "2026-12-02"
}
],
"delivery": {
"method": "electronic",
"why": null
},
"employer_qes": false,
"template_id": null,
"document_id": null,
"changed_fields": [],
"effective": null,
"blocked": null,
"sent": null,
"discarded_at": null,
"created_at": "2026-10-20T09:00:00.000Z",
"variant": null,
"warnings": [],
"decision": null,
"contract_end": null
},
{
"id": "prep2",
"person": {
"id": "p1",
"name": "Ana Ferreira"
},
"kind": "change_notice",
"reason": "change",
"status": "prepared",
"due_on": "2026-12-01",
"overdue": false,
"parts": [
{
"part": "all",
"due": "2026-12-01"
}
],
"delivery": {
"method": "electronic",
"why": null
},
"employer_qes": false,
"template_id": null,
"document_id": null,
"changed_fields": [
"job.title",
"pay.base"
],
"effective": "2026-12-01",
"blocked": null,
"sent": null,
"discarded_at": null,
"created_at": "2026-10-20T09:00:00.000Z",
"variant": null,
"warnings": [],
"decision": null,
"contract_end": null
}
],
"counts": {
"prepared": 2,
"overdue": 0,
"due_soon": 0
}
}
}Open a prepared document#
POST/v1/documents/prepared.getRead
One prepared document with its preview (HTML, filled for the person as it would be sent now), the values missing (nothing is sent with a blank), the template and language it uses, and its legal deadline. In the app only (it holds pay and private details). Owners, admins and HR.
- Web app only
- Refused for API keys and connected apps. Opening a prepared document (its preview holds pay and private details) is done in the app.
- MCP tool
documents_prepared_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
prepared_idstringrequired
Returns
preparedobjectrequired22 fields
idstringrequiredpersonobject | nullrequired2 fields
idstringrequirednamestringrequired
kindstring (enum)requiredstatement (written statement of working conditions), change_notice, or the kind of a generated draft.
One of:
contract_open,contract_fixed,contract_part_time,statement,amendment,change_notice,end_notice,certificate,declaration,policy,letter,offer_letter,pay_review_letter.reasonstring (enum)requiredhire, rehire, change (an approved change took effect), request (the person asked), current_staff, manual or bulk (drafts made with
documents_generate).One of:
hire,rehire,change,request,current_staff,manual,bulk,fixed_term_end,leaving,pay_review.status"prepared" | "sent" | "discarded"requireddue_onstring | nullrequiredThe legal deadline to give it to the person (null: none).
overduebooleanrequiredpartsobject[]requiredDeadlines per part (e.g. Germany: day 1, day 7, one month).
2 fields
partstringrequiredduestringrequired
deliveryobjectrequiredelectronic (My workspace, email, receipt to confirm) or print (NL without consent, a DE §2a sector).
2 fields
method"electronic" | "print"requiredwhy"nl_no_consent" | "de_sector" | "chosen" | "no_consent"required
employer_qesbooleanrequiredNL: sent electronically, it must carry the employer's qualified electronic signature: send a signed copy (signed_document_id).
template_idstring | nullrequirednull: the company's choice for the kind, else the country's built-in.
document_idstring | nullrequiredThe document once rendered (HR only until sent).
changed_fieldsstring[]requiredChange notices: the fields that changed (values only in the app, in the document).
effectivestring | nullrequiredChange notices: the day the change takes effect.
blockedobject | nullrequiredWhy it could not go out by itself on its deadline (statements): values missing, it goes on paper, or it needs your qualified signature.
3 fields
onstringrequiredwhystring (enum)requiredclause: a clause in it breaks the law for the person (regenerate it with other clause fields). visibility: its template shares pay or private details with managers. failed: it could not be made (storage full, the PDF); send it again.
One of:
missing,print,no_template,person_gone,qes,clause,visibility,failed.missingstring[]required
sentobject | nullrequiredProof of delivery: when it went, how, when the person first opened it and when they confirmed receipt.
6 fields
atstringrequiredby"hr" | "auto" | "self"requiredmethod"electronic" | "print"requiredhanded_over_onstring | nullrequiredopened_atstring | nullrequiredacknowledged_atstring | nullrequired
discarded_atstring | nullrequiredcreated_atstringrequiredvariant"renewal" | "reference" | "salary" | "employment"requiredStep 4: renewal (an amendment renewing a fixed-term contract), reference (DE qualified reference), salary or employment (declarations); null: the kind's own document.
warningsobject[]requiredWhat to know before sending: unilateral_notice (Spain, art. 41 ET: a substantial change the company decides alone reaches the person `days` days before, by `by`), protected_venue (Italy, art. 2103 c.c.: a downgrade is signed in a protected venue, never by click-to-accept), late (prepared after its legal deadline).
4 fields
code"unilateral_notice" | "protected_venue" | "late"requireddaysinteger | nullrequiredbystring | nullrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
decisionobject | nullrequiredEnd notices: what HR decided for the fixed-term contract (renew until new_end_date, permanent, or end); null until decided (it can't be sent before).
3 fields
outcome"renew" | "permanent" | "end"requirednew_end_datestring | nullrequiredtermsstring | nullrequired
contract_endstring | nullrequiredEnd notices: the contract's end date.
checkobjectrequired9 fields
missingstring[]requiredFields with no value: nothing is sent with a blank (fill them, or edit with overrides).
droppedstring[]requiredwithheldstring[]requiredtemplateobject | nullrequired3 fields
idstringrequirednamestringrequiredversionintegerrequired
language"en" | "pt" | "es" | "fr" | "de" | "it"requiredcountrystring | nullrequiredpreview_htmlstring | nullrequiredproblemstring | nullrequiredWhy it can't be made now (person gone, template archived…).
style"international" | "continental"requiredThe document style it is made in (null when it can't be made now).
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/prepared.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prepared_id":"prep1"}'const res = await fetch('https://api.bizisy.com/v1/documents/prepared.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"prepared_id": "prep1"
}),
});
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/documents/prepared.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"prepared_id": "prep1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"prepared": {
"id": "prep1",
"person": {
"id": "p1",
"name": "Ana Ferreira"
},
"kind": "statement",
"reason": "hire",
"status": "prepared",
"due_on": "2026-11-09",
"overdue": false,
"parts": [
{
"part": "core",
"due": "2026-11-09"
},
{
"part": "rest",
"due": "2026-12-02"
}
],
"delivery": {
"method": "electronic",
"why": null
},
"employer_qes": false,
"template_id": null,
"document_id": null,
"changed_fields": [],
"effective": null,
"blocked": null,
"sent": null,
"discarded_at": null,
"created_at": "2026-10-20T09:00:00.000Z",
"variant": null,
"warnings": [],
"decision": null,
"contract_end": null
},
"check": {
"missing": [],
"dropped": [
"job.schedule"
],
"withheld": [],
"template": {
"id": "builtin:pt.statement",
"name": "Written statement of working conditions (Portugal)",
"version": 1
},
"language": "pt",
"country": "PT",
"preview_html": "<!doctype html><html lang=\"pt\"><body>…</body></html>",
"problem": null,
"style": "continental"
}
}
}Send, edit or discard a prepared document#
POST/v1/documents/prepared.decideWrite
What HR does with a prepared document. action send: it goes to the person — electronically (default where allowed: it appears in their documents, they are emailed and asked to confirm receipt in My workspace; sent, first opened and confirmed are recorded as proof of delivery) or method print with handed_over_on (the day you handed the printed copy over; it stays HR's record). Netherlands: electronic only with the person's consent and the employer's qualified signature (upload the signed PDF to their documents, HR only, and pass signed_document_id); German §2a sectors: print. Nothing is sent with a missing value. action edit: overrides { <field path>: value } for this document only, template_id (another published template of the same kind), language and/or style (the document style: international or continental; null: the template's, else the company's, else the country's); the document is made again from them. action discard: it is not sent (its draft document is deleted). Use dry_run to see the result (preview, missing values) without changing anything. In the app only for send and edit (they hold pay and private details); API keys and AI assistants may discard. Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Machines may discard; sending and editing are done in the app.
- MCP tool
documents_prepared_decideon 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
prepared_idstringrequiredaction"send" | "edit" | "discard"requiredmethod"electronic" | "print"handed_over_onstringPattern
^\d{4}-\d{2}-\d{2}$.signed_document_idstringoverridesobjecttemplate_idstring | nulllanguage"en" | "pt" | "es" | "fr" | "de" | "it"style"international" | "continental"Edit: the document style (international or continental); null: the template's, else the company's, else the country's.
Returns
preparedobjectrequired22 fields
idstringrequiredpersonobject | nullrequired2 fields
idstringrequirednamestringrequired
kindstring (enum)requiredstatement (written statement of working conditions), change_notice, or the kind of a generated draft.
One of:
contract_open,contract_fixed,contract_part_time,statement,amendment,change_notice,end_notice,certificate,declaration,policy,letter,offer_letter,pay_review_letter.reasonstring (enum)requiredhire, rehire, change (an approved change took effect), request (the person asked), current_staff, manual or bulk (drafts made with
documents_generate).One of:
hire,rehire,change,request,current_staff,manual,bulk,fixed_term_end,leaving,pay_review.status"prepared" | "sent" | "discarded"requireddue_onstring | nullrequiredThe legal deadline to give it to the person (null: none).
overduebooleanrequiredpartsobject[]requiredDeadlines per part (e.g. Germany: day 1, day 7, one month).
2 fields
partstringrequiredduestringrequired
deliveryobjectrequiredelectronic (My workspace, email, receipt to confirm) or print (NL without consent, a DE §2a sector).
2 fields
method"electronic" | "print"requiredwhy"nl_no_consent" | "de_sector" | "chosen" | "no_consent"required
employer_qesbooleanrequiredNL: sent electronically, it must carry the employer's qualified electronic signature: send a signed copy (signed_document_id).
template_idstring | nullrequirednull: the company's choice for the kind, else the country's built-in.
document_idstring | nullrequiredThe document once rendered (HR only until sent).
changed_fieldsstring[]requiredChange notices: the fields that changed (values only in the app, in the document).
effectivestring | nullrequiredChange notices: the day the change takes effect.
blockedobject | nullrequiredWhy it could not go out by itself on its deadline (statements): values missing, it goes on paper, or it needs your qualified signature.
3 fields
onstringrequiredwhystring (enum)requiredclause: a clause in it breaks the law for the person (regenerate it with other clause fields). visibility: its template shares pay or private details with managers. failed: it could not be made (storage full, the PDF); send it again.
One of:
missing,print,no_template,person_gone,qes,clause,visibility,failed.missingstring[]required
sentobject | nullrequiredProof of delivery: when it went, how, when the person first opened it and when they confirmed receipt.
6 fields
atstringrequiredby"hr" | "auto" | "self"requiredmethod"electronic" | "print"requiredhanded_over_onstring | nullrequiredopened_atstring | nullrequiredacknowledged_atstring | nullrequired
discarded_atstring | nullrequiredcreated_atstringrequiredvariant"renewal" | "reference" | "salary" | "employment"requiredStep 4: renewal (an amendment renewing a fixed-term contract), reference (DE qualified reference), salary or employment (declarations); null: the kind's own document.
warningsobject[]requiredWhat to know before sending: unilateral_notice (Spain, art. 41 ET: a substantial change the company decides alone reaches the person `days` days before, by `by`), protected_venue (Italy, art. 2103 c.c.: a downgrade is signed in a protected venue, never by click-to-accept), late (prepared after its legal deadline).
4 fields
code"unilateral_notice" | "protected_venue" | "late"requireddaysinteger | nullrequiredbystring | nullrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
decisionobject | nullrequiredEnd notices: what HR decided for the fixed-term contract (renew until new_end_date, permanent, or end); null until decided (it can't be sent before).
3 fields
outcome"renew" | "permanent" | "end"requirednew_end_datestring | nullrequiredtermsstring | nullrequired
contract_endstring | nullrequiredEnd notices: the contract's end date.
checkobject | nullrequired9 fields
missingstring[]requiredFields with no value: nothing is sent with a blank (fill them, or edit with overrides).
droppedstring[]requiredwithheldstring[]requiredtemplateobject | nullrequired3 fields
idstringrequirednamestringrequiredversionintegerrequired
language"en" | "pt" | "es" | "fr" | "de" | "it"requiredcountrystring | nullrequiredpreview_htmlstring | nullrequiredproblemstring | nullrequiredWhy it can't be made now (person gone, template archived…).
style"international" | "continental"requiredThe document style it is made in (null when it can't be made now).
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/prepared.decide \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"prepared_id": "prep1",
"action": "edit",
"overrides": {
"leave.days_per_year": 25
},
"template_id": null,
"language": "en"
}'const res = await fetch('https://api.bizisy.com/v1/documents/prepared.decide', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"prepared_id": "prep1",
"action": "edit",
"overrides": {
"leave.days_per_year": 25
},
"template_id": null,
"language": "en"
}),
});
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/documents/prepared.decide",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"prepared_id": "prep1",
"action": "edit",
"overrides": {
"leave.days_per_year": 25,
},
"template_id": None,
"language": "en",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"prepared": {
"id": "prep3",
"person": {
"id": "p1",
"name": "Ana Ferreira"
},
"kind": "statement",
"reason": "hire",
"status": "sent",
"due_on": "2026-11-09",
"overdue": false,
"parts": [
{
"part": "core",
"due": "2026-11-09"
},
{
"part": "rest",
"due": "2026-12-02"
}
],
"delivery": {
"method": "electronic",
"why": null
},
"employer_qes": false,
"template_id": null,
"document_id": "d30",
"changed_fields": [],
"effective": null,
"blocked": null,
"sent": {
"at": "2026-10-21T09:00:00.000Z",
"by": "auto",
"method": "electronic",
"handed_over_on": null,
"opened_at": "2026-10-21T10:00:00.000Z",
"acknowledged_at": null
},
"discarded_at": null,
"created_at": "2026-10-20T09:00:00.000Z",
"variant": null,
"warnings": [],
"decision": null,
"contract_end": null
},
"check": null
}
}Prepare written statements for current staff#
POST/v1/documents/prepared.prepareWrite
Prepares the written statement of working conditions for people already employed (person_ids, or all_current true for everyone employed today, at most 500), each due one month from today (Spain: 30 working days), waiting for HR to review and send like the ones prepared at hire. People with a statement already waiting are skipped. Owners, admins and HR. Dry run supported (says how many).
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_prepared_prepareon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
person_idsstring[]1–500 items.
all_currentboolean
Returns
preparedintegerrequiredskippedintegerrequiredcappedbooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/prepared.prepare \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"person_ids":["p1","p2"]}'const res = await fetch('https://api.bizisy.com/v1/documents/prepared.prepare', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_ids": [
"p1",
"p2"
]
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/documents/prepared.prepare",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_ids": [
"p1",
"p2",
],
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"prepared": 12,
"skipped": 1,
"capped": false
}
}Create a document for someone#
POST/v1/documents/prepared.createWrite
Prepares one document for a person for HR to review and send (Documents → To review; nothing reaches the person before it is sent): kind amendment (an addendum to their contract for the change recorded on effective_date, default their latest change; variant renewal for a fixed-term renewal) — record the change first (it follows your approval rules), an amendment only documents it; end_notice (their fixed-term contract's end: decide renew, permanent or end with documents_prepared_contract before sending); certificate (a work certificate with their dates and positions; variant reference: the German qualified reference with an assessment HR writes in the edit step); declaration (variant employment or salary: a declaration of employment, or of employment and pay). template_id: a published template of that kind (default: your choice in Automatic documents, else the built-in for their country); language optional. The same one again on the same day returns the one already prepared. Through API keys and AI assistants an amendment never reads pay changes, and the result has no changed fields, dates or warnings. Owners, admins and HR. Dry run supported.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- Through machines, the amendment never reads pay changes.
- MCP tool
documents_prepared_createon 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_idstringrequiredkind"amendment" | "end_notice" | "certificate" | "declaration"requiredvariant"renewal" | "reference" | "salary" | "employment"effective_datestringAmendments: the day the change took (or takes) effect; default their latest change.
Pattern
^\d{4}-\d{2}-\d{2}$.template_idstring | nulllanguage"en" | "pt" | "es" | "fr" | "de" | "it"
Returns
preparedobjectrequired22 fields
idstringrequiredpersonobject | nullrequired2 fields
idstringrequirednamestringrequired
kindstring (enum)requiredstatement (written statement of working conditions), change_notice, or the kind of a generated draft.
One of:
contract_open,contract_fixed,contract_part_time,statement,amendment,change_notice,end_notice,certificate,declaration,policy,letter,offer_letter,pay_review_letter.reasonstring (enum)requiredhire, rehire, change (an approved change took effect), request (the person asked), current_staff, manual or bulk (drafts made with
documents_generate).One of:
hire,rehire,change,request,current_staff,manual,bulk,fixed_term_end,leaving,pay_review.status"prepared" | "sent" | "discarded"requireddue_onstring | nullrequiredThe legal deadline to give it to the person (null: none).
overduebooleanrequiredpartsobject[]requiredDeadlines per part (e.g. Germany: day 1, day 7, one month).
2 fields
partstringrequiredduestringrequired
deliveryobjectrequiredelectronic (My workspace, email, receipt to confirm) or print (NL without consent, a DE §2a sector).
2 fields
method"electronic" | "print"requiredwhy"nl_no_consent" | "de_sector" | "chosen" | "no_consent"required
employer_qesbooleanrequiredNL: sent electronically, it must carry the employer's qualified electronic signature: send a signed copy (signed_document_id).
template_idstring | nullrequirednull: the company's choice for the kind, else the country's built-in.
document_idstring | nullrequiredThe document once rendered (HR only until sent).
changed_fieldsstring[]requiredChange notices: the fields that changed (values only in the app, in the document).
effectivestring | nullrequiredChange notices: the day the change takes effect.
blockedobject | nullrequiredWhy it could not go out by itself on its deadline (statements): values missing, it goes on paper, or it needs your qualified signature.
3 fields
onstringrequiredwhystring (enum)requiredclause: a clause in it breaks the law for the person (regenerate it with other clause fields). visibility: its template shares pay or private details with managers. failed: it could not be made (storage full, the PDF); send it again.
One of:
missing,print,no_template,person_gone,qes,clause,visibility,failed.missingstring[]required
sentobject | nullrequiredProof of delivery: when it went, how, when the person first opened it and when they confirmed receipt.
6 fields
atstringrequiredby"hr" | "auto" | "self"requiredmethod"electronic" | "print"requiredhanded_over_onstring | nullrequiredopened_atstring | nullrequiredacknowledged_atstring | nullrequired
discarded_atstring | nullrequiredcreated_atstringrequiredvariant"renewal" | "reference" | "salary" | "employment"requiredStep 4: renewal (an amendment renewing a fixed-term contract), reference (DE qualified reference), salary or employment (declarations); null: the kind's own document.
warningsobject[]requiredWhat to know before sending: unilateral_notice (Spain, art. 41 ET: a substantial change the company decides alone reaches the person `days` days before, by `by`), protected_venue (Italy, art. 2103 c.c.: a downgrade is signed in a protected venue, never by click-to-accept), late (prepared after its legal deadline).
4 fields
code"unilateral_notice" | "protected_venue" | "late"requireddaysinteger | nullrequiredbystring | nullrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
decisionobject | nullrequiredEnd notices: what HR decided for the fixed-term contract (renew until new_end_date, permanent, or end); null until decided (it can't be sent before).
3 fields
outcome"renew" | "permanent" | "end"requirednew_end_datestring | nullrequiredtermsstring | nullrequired
contract_endstring | nullrequiredEnd notices: the contract's end date.
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/prepared.create \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"person_id": "p1",
"kind": "amendment",
"variant": "renewal",
"effective_date": "2026-11-01",
"template_id": null,
"language": "pt"
}'const res = await fetch('https://api.bizisy.com/v1/documents/prepared.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"person_id": "p1",
"kind": "amendment",
"variant": "renewal",
"effective_date": "2026-11-01",
"template_id": null,
"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/documents/prepared.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"person_id": "p1",
"kind": "amendment",
"variant": "renewal",
"effective_date": "2026-11-01",
"template_id": None,
"language": "pt",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"prepared": {
"id": "prep7",
"person": {
"id": "p1",
"name": "Ana Ferreira"
},
"kind": "amendment",
"reason": "manual",
"status": "prepared",
"due_on": null,
"overdue": false,
"parts": [],
"delivery": {
"method": "electronic",
"why": null
},
"employer_qes": false,
"template_id": null,
"document_id": null,
"changed_fields": [
"job.title",
"pay.base"
],
"effective": "2026-11-01",
"blocked": null,
"sent": null,
"discarded_at": null,
"created_at": "2026-10-20T09:00:00.000Z",
"variant": null,
"warnings": [
{
"code": "unilateral_notice",
"days": 15,
"by": "2026-10-17",
"source": {
"url": "https://www.boe.es/buscar/act.php?id=BOE-A-2015-11430",
"article": "art. 41 ET"
}
}
],
"decision": null,
"contract_end": null
}
}
}Decide a fixed-term contract from its end notice#
POST/v1/documents/prepared.contractWrite
What happens to a fixed-term contract, decided from its end notice (Documents → To review): outcome renew (new_end_date: a later end), permanent (an open-ended contract from the day after the end) or end (they leave on the end date). It is recorded in People through org_people_contract_decide (its approval rules and Portuguese warnings apply; a termination is kept from the person until the notice reaches them) and the notice says it; terms (optional) adds what changes. A change waiting for approval is not the decision yet: the notice follows once it is approved. A renewal or an open-ended contract also prepares the renewal addendum or the amendment (when fixed-term documents are on). Owners, admins and HR. Dry run supported.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_prepared_contracton 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
prepared_idstringrequiredoutcome"renew" | "permanent" | "end"requirednew_end_datestringPattern
^\d{4}-\d{2}-\d{2}$.termsstringWhat else continues or changes, in the document's language (e.g. "on the same terms, with a monthly base pay of €2,400").
Up to 500 characters.
Returns
preparedobjectrequired22 fields
idstringrequiredpersonobject | nullrequired2 fields
idstringrequirednamestringrequired
kindstring (enum)requiredstatement (written statement of working conditions), change_notice, or the kind of a generated draft.
One of:
contract_open,contract_fixed,contract_part_time,statement,amendment,change_notice,end_notice,certificate,declaration,policy,letter,offer_letter,pay_review_letter.reasonstring (enum)requiredhire, rehire, change (an approved change took effect), request (the person asked), current_staff, manual or bulk (drafts made with
documents_generate).One of:
hire,rehire,change,request,current_staff,manual,bulk,fixed_term_end,leaving,pay_review.status"prepared" | "sent" | "discarded"requireddue_onstring | nullrequiredThe legal deadline to give it to the person (null: none).
overduebooleanrequiredpartsobject[]requiredDeadlines per part (e.g. Germany: day 1, day 7, one month).
2 fields
partstringrequiredduestringrequired
deliveryobjectrequiredelectronic (My workspace, email, receipt to confirm) or print (NL without consent, a DE §2a sector).
2 fields
method"electronic" | "print"requiredwhy"nl_no_consent" | "de_sector" | "chosen" | "no_consent"required
employer_qesbooleanrequiredNL: sent electronically, it must carry the employer's qualified electronic signature: send a signed copy (signed_document_id).
template_idstring | nullrequirednull: the company's choice for the kind, else the country's built-in.
document_idstring | nullrequiredThe document once rendered (HR only until sent).
changed_fieldsstring[]requiredChange notices: the fields that changed (values only in the app, in the document).
effectivestring | nullrequiredChange notices: the day the change takes effect.
blockedobject | nullrequiredWhy it could not go out by itself on its deadline (statements): values missing, it goes on paper, or it needs your qualified signature.
3 fields
onstringrequiredwhystring (enum)requiredclause: a clause in it breaks the law for the person (regenerate it with other clause fields). visibility: its template shares pay or private details with managers. failed: it could not be made (storage full, the PDF); send it again.
One of:
missing,print,no_template,person_gone,qes,clause,visibility,failed.missingstring[]required
sentobject | nullrequiredProof of delivery: when it went, how, when the person first opened it and when they confirmed receipt.
6 fields
atstringrequiredby"hr" | "auto" | "self"requiredmethod"electronic" | "print"requiredhanded_over_onstring | nullrequiredopened_atstring | nullrequiredacknowledged_atstring | nullrequired
discarded_atstring | nullrequiredcreated_atstringrequiredvariant"renewal" | "reference" | "salary" | "employment"requiredStep 4: renewal (an amendment renewing a fixed-term contract), reference (DE qualified reference), salary or employment (declarations); null: the kind's own document.
warningsobject[]requiredWhat to know before sending: unilateral_notice (Spain, art. 41 ET: a substantial change the company decides alone reaches the person `days` days before, by `by`), protected_venue (Italy, art. 2103 c.c.: a downgrade is signed in a protected venue, never by click-to-accept), late (prepared after its legal deadline).
4 fields
code"unilateral_notice" | "protected_venue" | "late"requireddaysinteger | nullrequiredbystring | nullrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
decisionobject | nullrequiredEnd notices: what HR decided for the fixed-term contract (renew until new_end_date, permanent, or end); null until decided (it can't be sent before).
3 fields
outcome"renew" | "permanent" | "end"requirednew_end_datestring | nullrequiredtermsstring | nullrequired
contract_endstring | nullrequiredEnd notices: the contract's end date.
approval_pendingbooleanrequiredwarningsstring[]required
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/prepared.contract \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"prepared_id": "prep8",
"outcome": "renew",
"new_end_date": "2027-12-31",
"terms": "on the same terms"
}'const res = await fetch('https://api.bizisy.com/v1/documents/prepared.contract', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"prepared_id": "prep8",
"outcome": "renew",
"new_end_date": "2027-12-31",
"terms": "on the same terms"
}),
});
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/documents/prepared.contract",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"prepared_id": "prep8",
"outcome": "renew",
"new_end_date": "2027-12-31",
"terms": "on the same terms",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"prepared": {
"id": "prep8",
"person": {
"id": "p1",
"name": "Ana Ferreira"
},
"kind": "end_notice",
"reason": "fixed_term_end",
"status": "prepared",
"due_on": "2026-11-30",
"overdue": false,
"parts": [],
"delivery": {
"method": "electronic",
"why": null
},
"employer_qes": false,
"template_id": null,
"document_id": null,
"changed_fields": [],
"effective": null,
"blocked": null,
"sent": null,
"discarded_at": null,
"created_at": "2026-10-20T09:00:00.000Z",
"variant": null,
"warnings": [],
"decision": {
"outcome": "renew",
"new_end_date": "2027-12-31",
"terms": "on the same terms"
},
"contract_end": "2026-12-31"
},
"approval_pending": false,
"warnings": []
}
}List policies#
POST/v1/documents/policies.listRead
The policies published to staff (Documents → Policies): each with its template, who is asked (everyone or a saved group), the version people acknowledge now, whether a newer version of its template is published (publish it to ask again), and how many of the people asked acknowledged it and how many are missing. status: active (default) or retired, or all. person_id: only the active policies that person is asked to acknowledge, each with for_person (acknowledged when, or late). Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_policies_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
status"active" | "retired" | "all"person_idstring
Returns
policiesobject[]required12 fields
idstringrequiredtemplate_idstringrequirednamestringrequiredstatus"active" | "retired"requiredaudienceobjectrequiredgroup_id null: everyone employed; else the members of that saved group.
1 field
group_idstring | nullrequired
versionintegerrequiredThe version people are asked to acknowledge now.
template_versionintegerrequirednewer_template_versioninteger | nullrequiredA newer published version of its template (publish it to ask everyone again), else null.
published_atstringrequiredlanguages"en" | "pt" | "es" | "fr" | "de" | "it"[]requiredcountsobjectrequiredFor the current version, among the people asked today.
3 fields
askedintegerrequiredacknowledgedintegerrequiredmissingintegerrequired
for_personobjectWith person_id: whether that person acknowledged the current version (and when), or is late (asked more than 14 days ago).
2 fields
acknowledged_atstring | nullrequiredlatebooleanrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/policies.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status":"retired"}'const res = await fetch('https://api.bizisy.com/v1/documents/policies.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"status": "retired"
}),
});
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/documents/policies.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"status": "retired",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"policies": [
{
"id": "pol1",
"template_id": "builtin:all.policy_handbook",
"name": "Employee handbook",
"status": "active",
"audience": {
"group_id": null
},
"version": 2,
"template_version": 1,
"newer_template_version": null,
"published_at": "2026-10-20T09:00:00.000Z",
"languages": [
"en",
"pt"
],
"counts": {
"asked": 12,
"acknowledged": 9,
"missing": 3
}
}
]
}
}See who acknowledged a policy#
POST/v1/documents/policies.getRead
One policy: every person asked today with whether they acknowledged the current version (and when), the last version each acknowledged, the versions with how many acknowledged each, the works-council or posting steps of the countries they work in (information from the law pack, not legal advice), and what changed in the current version against the one before (word by word, in the company's language). Owners, admins and HR.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_policies_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
policy_idstringrequired
Returns
policyobjectrequired12 fields
idstringrequiredtemplate_idstringrequirednamestringrequiredstatus"active" | "retired"requiredaudienceobjectrequiredgroup_id null: everyone employed; else the members of that saved group.
1 field
group_idstring | nullrequired
versionintegerrequiredThe version people are asked to acknowledge now.
template_versionintegerrequirednewer_template_versioninteger | nullrequiredA newer published version of its template (publish it to ask everyone again), else null.
published_atstringrequiredlanguages"en" | "pt" | "es" | "fr" | "de" | "it"[]requiredcountsobjectrequiredFor the current version, among the people asked today.
3 fields
askedintegerrequiredacknowledgedintegerrequiredmissingintegerrequired
for_personobjectWith person_id: whether that person acknowledged the current version (and when), or is late (asked more than 14 days ago).
2 fields
acknowledged_atstring | nullrequiredlatebooleanrequired
peopleobject[]required4 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
acknowledged_atstring | nullrequiredlast_versioninteger | nullrequiredlatebooleanrequired
versionsobject[]required4 fields
versionintegerrequiredtemplate_versionintegerrequiredpublished_atstringrequiredacknowledgedintegerrequired
notesobject[]required3 fields
countrystringrequiredtextstringrequiredEnglish; the app translates it.
sourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
changesobject | nullrequired4 fields
from_versionintegerrequiredaddedintegerrequiredremovedintegerrequiredsegmentsobject[]required2 fields
op"eq" | "add" | "del"requiredtextstringrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/policies.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"policy_id":"pol1"}'const res = await fetch('https://api.bizisy.com/v1/documents/policies.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"policy_id": "pol1"
}),
});
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/documents/policies.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"policy_id": "pol1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"policy": {
"id": "pol1",
"template_id": "builtin:all.policy_handbook",
"name": "Employee handbook",
"status": "active",
"audience": {
"group_id": null
},
"version": 2,
"template_version": 1,
"newer_template_version": null,
"published_at": "2026-10-20T09:00:00.000Z",
"languages": [
"en",
"pt"
],
"counts": {
"asked": 12,
"acknowledged": 9,
"missing": 3
}
},
"people": [
{
"person": {
"id": "p1",
"name": "Ana Ferreira"
},
"acknowledged_at": "2026-10-21T09:00:00.000Z",
"last_version": 2,
"late": false
},
{
"person": {
"id": "p2",
"name": "Rui Costa"
},
"acknowledged_at": null,
"last_version": 1,
"late": true
}
],
"versions": [
{
"version": 1,
"template_version": 1,
"published_at": "2026-09-01T09:00:00.000Z",
"acknowledged": 11
},
{
"version": 2,
"template_version": 2,
"published_at": "2026-10-20T09:00:00.000Z",
"acknowledged": 9
}
],
"notes": [
{
"country": "FR",
"text": "A règlement intérieur goes to the CSE for its opinion first.",
"source": {
"url": "https://www.legifrance.gouv.fr/codes/article_lc/LEGIARTI000035652154",
"article": "Code du travail L1321-4"
}
}
],
"changes": {
"from_version": 1,
"added": 4,
"removed": 2,
"segments": [
{
"op": "eq",
"text": "Working hours are "
},
{
"op": "del",
"text": "9 to 5"
},
{
"op": "add",
"text": "9 to 6"
},
{
"op": "eq",
"text": "."
}
]
}
}
}Publish a policy to staff#
POST/v1/documents/policies.publishWrite
Publishes a policy template (kind policy, published; Bizisy's built-ins too) to everyone employed (group_id null or absent) or to the members of a saved group: each of them is asked to read and acknowledge it in My workspace ("I have read this"), new hires too, and reminded through the reminders digest after 14 days. Published again after its template has a newer published version, everyone is asked again and sees what changed; with only a different group_id, the audience changes. A policy can't use person, job or pay fields (it is the same for everyone). Check your country's steps first (in France the règlement intérieur goes to the works council, the labour inspectorate and the conseil de prud'hommes; works councils in Germany and the Netherlands; posting in Italy): documents_policies_get lists them. At most 50 active policies and 30 publishes a day. Owners, admins and HR. Dry run: who would be asked and what changed.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_policies_publishon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
template_idstringrequiredgroup_idstring | null
Returns
policyobjectrequired12 fields
idstringrequiredtemplate_idstringrequirednamestringrequiredstatus"active" | "retired"requiredaudienceobjectrequiredgroup_id null: everyone employed; else the members of that saved group.
1 field
group_idstring | nullrequired
versionintegerrequiredThe version people are asked to acknowledge now.
template_versionintegerrequirednewer_template_versioninteger | nullrequiredA newer published version of its template (publish it to ask everyone again), else null.
published_atstringrequiredlanguages"en" | "pt" | "es" | "fr" | "de" | "it"[]requiredcountsobjectrequiredFor the current version, among the people asked today.
3 fields
askedintegerrequiredacknowledgedintegerrequiredmissingintegerrequired
for_personobjectWith person_id: whether that person acknowledged the current version (and when), or is late (asked more than 14 days ago).
2 fields
acknowledged_atstring | nullrequiredlatebooleanrequired
askedintegerrequirednew_versionbooleanrequiredchangesobject | nullrequired2 fields
addedintegerrequiredremovedintegerrequired
notesobject[]required3 fields
countrystringrequiredtextstringrequiredEnglish; the app translates it.
sourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/policies.publish \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"template_id":"builtin:all.policy_handbook"}'const res = await fetch('https://api.bizisy.com/v1/documents/policies.publish', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"template_id": "builtin:all.policy_handbook"
}),
});
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/documents/policies.publish",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"template_id": "builtin:all.policy_handbook",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"policy": {
"id": "pol1",
"template_id": "builtin:all.policy_handbook",
"name": "Employee handbook",
"status": "active",
"audience": {
"group_id": null
},
"version": 2,
"template_version": 1,
"newer_template_version": null,
"published_at": "2026-10-20T09:00:00.000Z",
"languages": [
"en",
"pt"
],
"counts": {
"asked": 12,
"acknowledged": 9,
"missing": 3
}
},
"asked": 12,
"new_version": true,
"changes": {
"added": 4,
"removed": 2
},
"notes": [
{
"country": "FR",
"text": "A règlement intérieur goes to the CSE for its opinion first.",
"source": {
"url": "https://www.legifrance.gouv.fr/codes/article_lc/LEGIARTI000035652154",
"article": "Code du travail L1321-4"
}
}
]
}
}Retire a policy#
POST/v1/documents/policies.retireWrite
Stops asking people to acknowledge a policy (it is no longer in force, or replaced by another). The acknowledgements given stay as the record. Owners, admins and HR. Dry run supported.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_policies_retireon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
policy_idstringrequired
Returns
policyobjectrequired12 fields
idstringrequiredtemplate_idstringrequirednamestringrequiredstatus"active" | "retired"requiredaudienceobjectrequiredgroup_id null: everyone employed; else the members of that saved group.
1 field
group_idstring | nullrequired
versionintegerrequiredThe version people are asked to acknowledge now.
template_versionintegerrequirednewer_template_versioninteger | nullrequiredA newer published version of its template (publish it to ask everyone again), else null.
published_atstringrequiredlanguages"en" | "pt" | "es" | "fr" | "de" | "it"[]requiredcountsobjectrequiredFor the current version, among the people asked today.
3 fields
askedintegerrequiredacknowledgedintegerrequiredmissingintegerrequired
for_personobjectWith person_id: whether that person acknowledged the current version (and when), or is late (asked more than 14 days ago).
2 fields
acknowledged_atstring | nullrequiredlatebooleanrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/policies.retire \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"policy_id":"pol1"}'const res = await fetch('https://api.bizisy.com/v1/documents/policies.retire', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"policy_id": "pol1"
}),
});
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/documents/policies.retire",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"policy_id": "pol1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"policy": {
"id": "pol1",
"template_id": "builtin:all.policy_handbook",
"name": "Employee handbook",
"status": "retired",
"audience": {
"group_id": null
},
"version": 2,
"template_version": 1,
"newer_template_version": null,
"published_at": "2026-10-20T09:00:00.000Z",
"languages": [
"en",
"pt"
],
"counts": {
"asked": 0,
"acknowledged": 0,
"missing": 0
}
}
}
}List contract clauses#
POST/v1/documents/clauses.listRead
The clause library: Bizisy's starter clauses (source builtin; one per clause type and country: PT, ES, FR, DE, IT, NL, and EU for any other country; not yet reviewed by a lawyer) and your company's own (drafts and published; archived with status archived or all). Clause types: non_compete, non_solicitation, probation, training_repayment, remote_work, exclusivity, confidentiality, ip_inventions, mobility, overtime_included, notice, garden_leave, equipment, monitoring_notice, collective_agreement, pay_extra_months. Filters: type, country (any 2-letter code: its rules, or the EU minimum), status, source. Each: category, country, languages, status, version. Texts, fields and law notes come from documents_clauses_get. Owners, admins and HR; API keys and AI assistants may read.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_clauses_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
typestring (enum)One of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months.countrystringPattern
^[A-Z]{2}$.status"draft" | "published" | "archived" | "all"Default: drafts and published.
source"builtin" | "company"
Returns
clausesobject[]required13 fields
idstringrequiredA company clause's id, or a starter's (builtin:clause.<country>.<type>).
source"builtin" | "company"requiredbuiltin: Bizisy's starter (copy it to change it); company: your own.
typestring (enum)requiredOne of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months.category"restrictions" | "start_and_end" | "pay_and_time" | "how_we_work" | "rights"requiredcountrystring (enum)requiredWhose rules it runs (EU: the EU minimum, for any other country).
One of:
PT,ES,FR,DE,IT,NL,EU.namestringrequiredlanguages"en" | "pt" | "es" | "fr" | "de" | "it"[]requiredstatus"draft" | "published" | "archived"requiredversionintegerrequiredThe latest published version (0: never published).
has_draftbooleanrequiredreviewedboolean | nullrequiredStarters: a local employment lawyer reviewed the text (false: not yet). null for your own.
builtin_fromstring | nullrequiredupdated_atstring | nullrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/clauses.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"type":"non_compete","country":"AT","status":"all","source":"company"}'const res = await fetch('https://api.bizisy.com/v1/documents/clauses.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"type": "non_compete",
"country": "AT",
"status": "all",
"source": "company"
}),
});
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/documents/clauses.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"type": "non_compete",
"country": "AT",
"status": "all",
"source": "company",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"clauses": [
{
"id": "builtin:clause.de.non_compete",
"source": "builtin",
"type": "non_compete",
"category": "restrictions",
"country": "DE",
"name": "Non-compete after leaving (Germany)",
"languages": [
"en",
"pt",
"es",
"fr",
"de",
"it"
],
"status": "published",
"version": 1,
"has_draft": false,
"reviewed": false,
"builtin_from": null,
"updated_at": null
},
{
"id": "cl1",
"source": "company",
"type": "non_compete",
"category": "restrictions",
"country": "DE",
"name": "Our non-compete (Germany)",
"languages": [
"de",
"en"
],
"status": "published",
"version": 2,
"has_draft": true,
"reviewed": null,
"builtin_from": "builtin:clause.de.non_compete",
"updated_at": "2026-10-19T10:00:00.000Z"
}
]
}
}Get a contract clause#
POST/v1/documents/clauses.getRead
One clause (a starter or your own) with its text per language (the draft for your own), your defaults for its typed fields, published versions, lint warnings, forbidden wording found, how many documents use it, and the law for its type and country: the typed fields (name, type, unit, required, default, allowed values), the rules (block: the law Bizisy treats as settled; warn: less certain), the law note with its sources and confidence, and the signature level it raises a document to. A starting point, not legal advice.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_clauses_geton HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
clause_idstringrequired
Returns
20 fields
idstringrequiredA company clause's id, or a starter's (builtin:clause.<country>.<type>).
source"builtin" | "company"requiredbuiltin: Bizisy's starter (copy it to change it); company: your own.
typestring (enum)requiredOne of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months.category"restrictions" | "start_and_end" | "pay_and_time" | "how_we_work" | "rights"requiredcountrystring (enum)requiredWhose rules it runs (EU: the EU minimum, for any other country).
One of:
PT,ES,FR,DE,IT,NL,EU.namestringrequiredlanguages"en" | "pt" | "es" | "fr" | "de" | "it"[]requiredstatus"draft" | "published" | "archived"requiredversionintegerrequiredThe latest published version (0: never published).
has_draftbooleanrequiredreviewedboolean | nullrequiredStarters: a local employment lawyer reviewed the text (false: not yet). null for your own.
builtin_fromstring | nullrequiredupdated_atstring | nullrequiredbodiesobjectrequired6 fields
enobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
ptobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
esobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
frobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
deobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
itobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
defaultsobjectrequiredYour defaults for its typed fields (HR changes them per document).
versionsobject[]required2 fields
versionintegerrequiredpublished_atstringrequired
problemsobject[]requiredLint warnings in the draft (errors are refused when saving).
8 fields
language"en" | "pt" | "es" | "fr" | "de" | "it"requiredfield"title" | "body"requiredlineintegerrequiredcolintegerrequiredcodestringrequiredmessagestringrequiredseverity"error" | "warning"requiredparamsobject
wordingobject[]requiredWording the rules forbid (pay secrecy, automatic termination, pay fines): blocks refuse publishing.
6 fields
rulestringrequiredmessagestringrequiredEnglish with {params}; the app translates it.
paramsobject | nullrequiredfieldstring | nullrequiredThe typed field it is about.
sourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"required
variantobjectrequiredThe law for its clause type and country: fields, rules, note and sources.
11 fields
countrystring (enum)requiredOne of:
PT,ES,FR,DE,IT,NL,EU.notestringrequiredWhat the law says here (English; the app translates it).
sourcesobject[]required2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requiredlast_reviewedstringrequiredeffective_fromstringrequiredeffective_tostring | nullrequiredreviewedbooleanrequiredfieldsobject[]required10 fields
namestringrequiredtype"number" | "text" | "boolean" | "enum" | "list" | "money"requiredlabelstringrequiredEnglish; the app translates it.
unitstring | nullrequiredrequiredbooleanrequireddefaultanyvaluesobject[] | nullrequired2 fields
valuestringrequiredlabelstringrequired
minnumber | nullrequiredmaxnumber | nullrequiredhintstring | nullrequired
rulesobject[]required6 fields
idstringrequiredseverity"block" | "warn"requiredmessagestringrequiredfieldstring | nullrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"required
raises_toobject | nullrequired2 fields
level"none" | "simple" | "advanced" | "qualified" | "wet"requiredconfidence"verified" | "medium" | "uncertain"required
documentsintegerrequiredDocuments made with it.
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/clauses.get \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"clause_id":"builtin:clause.de.non_compete"}'const res = await fetch('https://api.bizisy.com/v1/documents/clauses.get', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"clause_id": "builtin:clause.de.non_compete"
}),
});
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/documents/clauses.get",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"clause_id": "builtin:clause.de.non_compete",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "cl1",
"source": "company",
"type": "non_compete",
"category": "restrictions",
"country": "DE",
"name": "Our non-compete (Germany)",
"languages": [
"de",
"en"
],
"status": "published",
"version": 2,
"has_draft": true,
"reviewed": null,
"builtin_from": "builtin:clause.de.non_compete",
"updated_at": "2026-10-19T10:00:00.000Z",
"bodies": {
"de": {
"title": "Nachvertragliches Wettbewerbsverbot",
"body": "Für {{clause.duration_months}} Monate …"
},
"en": {
"title": "Post-contractual non-compete",
"body": "For {{clause.duration_months}} months …"
}
},
"defaults": {
"compensation_pct": 60
},
"versions": [
{
"version": 2,
"published_at": "2026-10-19T10:00:00.000Z"
},
{
"version": 1,
"published_at": "2026-10-18T10:00:00.000Z"
}
],
"problems": [],
"wording": [],
"variant": {
"country": "DE",
"note": "Written and signed, with the signed document handed over; at least 50% of the last total pay, monthly, for up to 2 years; never with a minor.",
"sources": [
{
"url": "https://www.gesetze-im-internet.de/hgb/__74.html",
"article": "HGB §74 Abs. 1 und 2"
}
],
"confidence": "medium",
"last_reviewed": "2026-10-19",
"effective_from": "2000-01-01",
"effective_to": null,
"reviewed": false,
"fields": [
{
"name": "duration_months",
"type": "number",
"label": "How long after leaving",
"unit": "months",
"required": true,
"default": 12,
"values": null,
"min": 0,
"max": 60,
"hint": null
},
{
"name": "compensation_pct",
"type": "number",
"label": "Compensation, % of pay",
"unit": "percent",
"required": true,
"default": 50,
"values": null,
"min": 50,
"max": 100,
"hint": "At least half the last total pay, for each year of the restriction."
},
{
"name": "waiver",
"type": "enum",
"label": "Waiver",
"unit": null,
"required": true,
"default": "none",
"values": [
{
"value": "none",
"label": "No waiver"
},
{
"value": "mutual",
"label": "Only by agreement of both"
}
],
"min": null,
"max": null,
"hint": null
}
],
"rules": [
{
"id": "de.nc_pay",
"severity": "block",
"message": "In Germany the compensation is at least 50% of the last total pay (HGB §74(2)); below that the person is not bound.",
"field": "compensation_pct",
"source": {
"url": "https://www.gesetze-im-internet.de/hgb/__74.html",
"article": "HGB §74 Abs. 1 und 2"
},
"confidence": "medium"
}
],
"raises_to": {
"level": "qualified",
"confidence": "verified"
}
},
"documents": 3
}
}Create a contract clause#
POST/v1/documents/clauses.createWrite
Creates a draft clause of your company for one clause type and one country's rules (PT, ES, FR, DE, IT, NL, or any other code for the EU minimum): name, bodies per language (en, pt, es, fr, de, it: { title, body }; the title is the heading in the document; the body is Markdown-lite without headings, with {{clause.<field>}} for its typed fields and document fields such as {{employer.legal_name}}; no pay or private details), and defaults for its typed fields (documents_clauses_get on a starter lists them). Lint errors refuse the save with each problem. Your clause still runs the country's rules when a document is made (blocks refuse it, warnings show). Publish it to use it. At most 300 clauses. Owners, admins and HR, in the web app.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_clauses_createon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
typestring (enum)requiredOne of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months.countrystringrequiredPattern
^[A-Z]{2}$.namestringrequired1–120 characters.
bodiesobjectrequired6 fields
enobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
ptobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
esobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
frobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
deobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
itobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
defaultsobject
Returns
20 fields
idstringrequiredA company clause's id, or a starter's (builtin:clause.<country>.<type>).
source"builtin" | "company"requiredbuiltin: Bizisy's starter (copy it to change it); company: your own.
typestring (enum)requiredOne of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months.category"restrictions" | "start_and_end" | "pay_and_time" | "how_we_work" | "rights"requiredcountrystring (enum)requiredWhose rules it runs (EU: the EU minimum, for any other country).
One of:
PT,ES,FR,DE,IT,NL,EU.namestringrequiredlanguages"en" | "pt" | "es" | "fr" | "de" | "it"[]requiredstatus"draft" | "published" | "archived"requiredversionintegerrequiredThe latest published version (0: never published).
has_draftbooleanrequiredreviewedboolean | nullrequiredStarters: a local employment lawyer reviewed the text (false: not yet). null for your own.
builtin_fromstring | nullrequiredupdated_atstring | nullrequiredbodiesobjectrequired6 fields
enobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
ptobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
esobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
frobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
deobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
itobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
defaultsobjectrequiredYour defaults for its typed fields (HR changes them per document).
versionsobject[]required2 fields
versionintegerrequiredpublished_atstringrequired
problemsobject[]requiredLint warnings in the draft (errors are refused when saving).
8 fields
language"en" | "pt" | "es" | "fr" | "de" | "it"requiredfield"title" | "body"requiredlineintegerrequiredcolintegerrequiredcodestringrequiredmessagestringrequiredseverity"error" | "warning"requiredparamsobject
wordingobject[]requiredWording the rules forbid (pay secrecy, automatic termination, pay fines): blocks refuse publishing.
6 fields
rulestringrequiredmessagestringrequiredEnglish with {params}; the app translates it.
paramsobject | nullrequiredfieldstring | nullrequiredThe typed field it is about.
sourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"required
variantobjectrequiredThe law for its clause type and country: fields, rules, note and sources.
11 fields
countrystring (enum)requiredOne of:
PT,ES,FR,DE,IT,NL,EU.notestringrequiredWhat the law says here (English; the app translates it).
sourcesobject[]required2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requiredlast_reviewedstringrequiredeffective_fromstringrequiredeffective_tostring | nullrequiredreviewedbooleanrequiredfieldsobject[]required10 fields
namestringrequiredtype"number" | "text" | "boolean" | "enum" | "list" | "money"requiredlabelstringrequiredEnglish; the app translates it.
unitstring | nullrequiredrequiredbooleanrequireddefaultanyvaluesobject[] | nullrequired2 fields
valuestringrequiredlabelstringrequired
minnumber | nullrequiredmaxnumber | nullrequiredhintstring | nullrequired
rulesobject[]required6 fields
idstringrequiredseverity"block" | "warn"requiredmessagestringrequiredfieldstring | nullrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"required
raises_toobject | nullrequired2 fields
level"none" | "simple" | "advanced" | "qualified" | "wet"requiredconfidence"verified" | "medium" | "uncertain"required
documentsintegerrequiredDocuments made with it.
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/clauses.create \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"type": "probation",
"country": "ES",
"name": "Período de prueba",
"bodies": {
"es": {
"title": "Período de prueba",
"body": "{{clause.duration}} meses: {{#each clause.assessed_tasks}}\n- {{this}}\n{{/each}}"
}
},
"defaults": {
"duration": 2,
"duration_unit": "months"
}
}'const res = await fetch('https://api.bizisy.com/v1/documents/clauses.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"type": "probation",
"country": "ES",
"name": "Período de prueba",
"bodies": {
"es": {
"title": "Período de prueba",
"body": "{{clause.duration}} meses: {{#each clause.assessed_tasks}}\n- {{this}}\n{{/each}}"
}
},
"defaults": {
"duration": 2,
"duration_unit": "months"
}
}),
});
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/documents/clauses.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"type": "probation",
"country": "ES",
"name": "Período de prueba",
"bodies": {
"es": {
"title": "Período de prueba",
"body": "{{clause.duration}} meses: {{#each clause.assessed_tasks}}\n- {{this}}\n{{/each}}",
},
},
"defaults": {
"duration": 2,
"duration_unit": "months",
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "cl1",
"source": "company",
"type": "probation",
"category": "restrictions",
"country": "ES",
"name": "Período de prueba",
"languages": [
"de",
"en"
],
"status": "draft",
"version": 0,
"has_draft": true,
"reviewed": null,
"builtin_from": "builtin:clause.de.non_compete",
"updated_at": "2026-10-19T10:00:00.000Z",
"bodies": {
"de": {
"title": "Nachvertragliches Wettbewerbsverbot",
"body": "Für {{clause.duration_months}} Monate …"
},
"en": {
"title": "Post-contractual non-compete",
"body": "For {{clause.duration_months}} months …"
}
},
"defaults": {
"compensation_pct": 60
},
"versions": [],
"problems": [],
"wording": [],
"variant": {
"country": "DE",
"note": "Written and signed, with the signed document handed over; at least 50% of the last total pay, monthly, for up to 2 years; never with a minor.",
"sources": [
{
"url": "https://www.gesetze-im-internet.de/hgb/__74.html",
"article": "HGB §74 Abs. 1 und 2"
}
],
"confidence": "medium",
"last_reviewed": "2026-10-19",
"effective_from": "2000-01-01",
"effective_to": null,
"reviewed": false,
"fields": [
{
"name": "duration_months",
"type": "number",
"label": "How long after leaving",
"unit": "months",
"required": true,
"default": 12,
"values": null,
"min": 0,
"max": 60,
"hint": null
},
{
"name": "compensation_pct",
"type": "number",
"label": "Compensation, % of pay",
"unit": "percent",
"required": true,
"default": 50,
"values": null,
"min": 50,
"max": 100,
"hint": "At least half the last total pay, for each year of the restriction."
},
{
"name": "waiver",
"type": "enum",
"label": "Waiver",
"unit": null,
"required": true,
"default": "none",
"values": [
{
"value": "none",
"label": "No waiver"
},
{
"value": "mutual",
"label": "Only by agreement of both"
}
],
"min": null,
"max": null,
"hint": null
}
],
"rules": [
{
"id": "de.nc_pay",
"severity": "block",
"message": "In Germany the compensation is at least 50% of the last total pay (HGB §74(2)); below that the person is not bound.",
"field": "compensation_pct",
"source": {
"url": "https://www.gesetze-im-internet.de/hgb/__74.html",
"article": "HGB §74 Abs. 1 und 2"
},
"confidence": "medium"
}
],
"raises_to": {
"level": "qualified",
"confidence": "verified"
}
},
"documents": 3
}
}Edit a contract clause#
POST/v1/documents/clauses.updateWrite
Edits the draft of one of your clauses: name, bodies (the whole set of languages: one left out is removed), defaults of its typed fields. Published versions never change: publish the draft to make a new version. Lint errors refuse the save. Starters can't be edited: copy them first. Owners, admins and HR, in the web app.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_clauses_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
clause_idstringrequirednamestring1–120 characters.
bodiesobject6 fields
enobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
ptobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
esobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
frobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
deobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
itobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
defaultsobject
Returns
20 fields
idstringrequiredA company clause's id, or a starter's (builtin:clause.<country>.<type>).
source"builtin" | "company"requiredbuiltin: Bizisy's starter (copy it to change it); company: your own.
typestring (enum)requiredOne of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months.category"restrictions" | "start_and_end" | "pay_and_time" | "how_we_work" | "rights"requiredcountrystring (enum)requiredWhose rules it runs (EU: the EU minimum, for any other country).
One of:
PT,ES,FR,DE,IT,NL,EU.namestringrequiredlanguages"en" | "pt" | "es" | "fr" | "de" | "it"[]requiredstatus"draft" | "published" | "archived"requiredversionintegerrequiredThe latest published version (0: never published).
has_draftbooleanrequiredreviewedboolean | nullrequiredStarters: a local employment lawyer reviewed the text (false: not yet). null for your own.
builtin_fromstring | nullrequiredupdated_atstring | nullrequiredbodiesobjectrequired6 fields
enobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
ptobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
esobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
frobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
deobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
itobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
defaultsobjectrequiredYour defaults for its typed fields (HR changes them per document).
versionsobject[]required2 fields
versionintegerrequiredpublished_atstringrequired
problemsobject[]requiredLint warnings in the draft (errors are refused when saving).
8 fields
language"en" | "pt" | "es" | "fr" | "de" | "it"requiredfield"title" | "body"requiredlineintegerrequiredcolintegerrequiredcodestringrequiredmessagestringrequiredseverity"error" | "warning"requiredparamsobject
wordingobject[]requiredWording the rules forbid (pay secrecy, automatic termination, pay fines): blocks refuse publishing.
6 fields
rulestringrequiredmessagestringrequiredEnglish with {params}; the app translates it.
paramsobject | nullrequiredfieldstring | nullrequiredThe typed field it is about.
sourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"required
variantobjectrequiredThe law for its clause type and country: fields, rules, note and sources.
11 fields
countrystring (enum)requiredOne of:
PT,ES,FR,DE,IT,NL,EU.notestringrequiredWhat the law says here (English; the app translates it).
sourcesobject[]required2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requiredlast_reviewedstringrequiredeffective_fromstringrequiredeffective_tostring | nullrequiredreviewedbooleanrequiredfieldsobject[]required10 fields
namestringrequiredtype"number" | "text" | "boolean" | "enum" | "list" | "money"requiredlabelstringrequiredEnglish; the app translates it.
unitstring | nullrequiredrequiredbooleanrequireddefaultanyvaluesobject[] | nullrequired2 fields
valuestringrequiredlabelstringrequired
minnumber | nullrequiredmaxnumber | nullrequiredhintstring | nullrequired
rulesobject[]required6 fields
idstringrequiredseverity"block" | "warn"requiredmessagestringrequiredfieldstring | nullrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"required
raises_toobject | nullrequired2 fields
level"none" | "simple" | "advanced" | "qualified" | "wet"requiredconfidence"verified" | "medium" | "uncertain"required
documentsintegerrequiredDocuments made with it.
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/clauses.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"clause_id": "cl1",
"bodies": {
"en": {
"title": "Non-compete",
"body": "x"
}
},
"defaults": {
"compensation_pct": 60,
"waiver": "mutual",
"equipment": [
"Laptop"
],
"paid": true,
"geography": null
}
}'const res = await fetch('https://api.bizisy.com/v1/documents/clauses.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"clause_id": "cl1",
"bodies": {
"en": {
"title": "Non-compete",
"body": "x"
}
},
"defaults": {
"compensation_pct": 60,
"waiver": "mutual",
"equipment": [
"Laptop"
],
"paid": true,
"geography": null
}
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/documents/clauses.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"clause_id": "cl1",
"bodies": {
"en": {
"title": "Non-compete",
"body": "x",
},
},
"defaults": {
"compensation_pct": 60,
"waiver": "mutual",
"equipment": [
"Laptop",
],
"paid": True,
"geography": None,
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "cl1",
"source": "company",
"type": "non_compete",
"category": "restrictions",
"country": "DE",
"name": "Our non-compete (Germany)",
"languages": [
"de",
"en"
],
"status": "published",
"version": 2,
"has_draft": true,
"reviewed": null,
"builtin_from": "builtin:clause.de.non_compete",
"updated_at": "2026-10-19T10:00:00.000Z",
"bodies": {
"de": {
"title": "Nachvertragliches Wettbewerbsverbot",
"body": "Für {{clause.duration_months}} Monate …"
},
"en": {
"title": "Post-contractual non-compete",
"body": "For {{clause.duration_months}} months …"
}
},
"defaults": {
"compensation_pct": 60
},
"versions": [
{
"version": 2,
"published_at": "2026-10-19T10:00:00.000Z"
},
{
"version": 1,
"published_at": "2026-10-18T10:00:00.000Z"
}
],
"problems": [],
"wording": [],
"variant": {
"country": "DE",
"note": "Written and signed, with the signed document handed over; at least 50% of the last total pay, monthly, for up to 2 years; never with a minor.",
"sources": [
{
"url": "https://www.gesetze-im-internet.de/hgb/__74.html",
"article": "HGB §74 Abs. 1 und 2"
}
],
"confidence": "medium",
"last_reviewed": "2026-10-19",
"effective_from": "2000-01-01",
"effective_to": null,
"reviewed": false,
"fields": [
{
"name": "duration_months",
"type": "number",
"label": "How long after leaving",
"unit": "months",
"required": true,
"default": 12,
"values": null,
"min": 0,
"max": 60,
"hint": null
},
{
"name": "compensation_pct",
"type": "number",
"label": "Compensation, % of pay",
"unit": "percent",
"required": true,
"default": 50,
"values": null,
"min": 50,
"max": 100,
"hint": "At least half the last total pay, for each year of the restriction."
},
{
"name": "waiver",
"type": "enum",
"label": "Waiver",
"unit": null,
"required": true,
"default": "none",
"values": [
{
"value": "none",
"label": "No waiver"
},
{
"value": "mutual",
"label": "Only by agreement of both"
}
],
"min": null,
"max": null,
"hint": null
}
],
"rules": [
{
"id": "de.nc_pay",
"severity": "block",
"message": "In Germany the compensation is at least 50% of the last total pay (HGB §74(2)); below that the person is not bound.",
"field": "compensation_pct",
"source": {
"url": "https://www.gesetze-im-internet.de/hgb/__74.html",
"article": "HGB §74 Abs. 1 und 2"
},
"confidence": "medium"
}
],
"raises_to": {
"level": "qualified",
"confidence": "verified"
}
},
"documents": 3
}
}Copy a contract clause#
POST/v1/documents/clauses.copyWrite
Makes a draft copy of a starter clause (to adapt Bizisy's wording) or of one of yours: same type, country, texts and defaults; name optional. Owners, admins and HR, in the web app.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_clauses_copyon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
clause_idstringrequirednamestring1–120 characters.
Returns
20 fields
idstringrequiredA company clause's id, or a starter's (builtin:clause.<country>.<type>).
source"builtin" | "company"requiredbuiltin: Bizisy's starter (copy it to change it); company: your own.
typestring (enum)requiredOne of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months.category"restrictions" | "start_and_end" | "pay_and_time" | "how_we_work" | "rights"requiredcountrystring (enum)requiredWhose rules it runs (EU: the EU minimum, for any other country).
One of:
PT,ES,FR,DE,IT,NL,EU.namestringrequiredlanguages"en" | "pt" | "es" | "fr" | "de" | "it"[]requiredstatus"draft" | "published" | "archived"requiredversionintegerrequiredThe latest published version (0: never published).
has_draftbooleanrequiredreviewedboolean | nullrequiredStarters: a local employment lawyer reviewed the text (false: not yet). null for your own.
builtin_fromstring | nullrequiredupdated_atstring | nullrequiredbodiesobjectrequired6 fields
enobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
ptobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
esobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
frobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
deobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
itobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
defaultsobjectrequiredYour defaults for its typed fields (HR changes them per document).
versionsobject[]required2 fields
versionintegerrequiredpublished_atstringrequired
problemsobject[]requiredLint warnings in the draft (errors are refused when saving).
8 fields
language"en" | "pt" | "es" | "fr" | "de" | "it"requiredfield"title" | "body"requiredlineintegerrequiredcolintegerrequiredcodestringrequiredmessagestringrequiredseverity"error" | "warning"requiredparamsobject
wordingobject[]requiredWording the rules forbid (pay secrecy, automatic termination, pay fines): blocks refuse publishing.
6 fields
rulestringrequiredmessagestringrequiredEnglish with {params}; the app translates it.
paramsobject | nullrequiredfieldstring | nullrequiredThe typed field it is about.
sourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"required
variantobjectrequiredThe law for its clause type and country: fields, rules, note and sources.
11 fields
countrystring (enum)requiredOne of:
PT,ES,FR,DE,IT,NL,EU.notestringrequiredWhat the law says here (English; the app translates it).
sourcesobject[]required2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requiredlast_reviewedstringrequiredeffective_fromstringrequiredeffective_tostring | nullrequiredreviewedbooleanrequiredfieldsobject[]required10 fields
namestringrequiredtype"number" | "text" | "boolean" | "enum" | "list" | "money"requiredlabelstringrequiredEnglish; the app translates it.
unitstring | nullrequiredrequiredbooleanrequireddefaultanyvaluesobject[] | nullrequired2 fields
valuestringrequiredlabelstringrequired
minnumber | nullrequiredmaxnumber | nullrequiredhintstring | nullrequired
rulesobject[]required6 fields
idstringrequiredseverity"block" | "warn"requiredmessagestringrequiredfieldstring | nullrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"required
raises_toobject | nullrequired2 fields
level"none" | "simple" | "advanced" | "qualified" | "wet"requiredconfidence"verified" | "medium" | "uncertain"required
documentsintegerrequiredDocuments made with it.
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/clauses.copy \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"clause_id":"builtin:clause.de.non_compete"}'const res = await fetch('https://api.bizisy.com/v1/documents/clauses.copy', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"clause_id": "builtin:clause.de.non_compete"
}),
});
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/documents/clauses.copy",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"clause_id": "builtin:clause.de.non_compete",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "cl1",
"source": "company",
"type": "non_compete",
"category": "restrictions",
"country": "DE",
"name": "Our non-compete (Germany)",
"languages": [
"de",
"en"
],
"status": "draft",
"version": 0,
"has_draft": true,
"reviewed": null,
"builtin_from": "builtin:clause.de.non_compete",
"updated_at": "2026-10-19T10:00:00.000Z",
"bodies": {
"de": {
"title": "Nachvertragliches Wettbewerbsverbot",
"body": "Für {{clause.duration_months}} Monate …"
},
"en": {
"title": "Post-contractual non-compete",
"body": "For {{clause.duration_months}} months …"
}
},
"defaults": {
"compensation_pct": 60
},
"versions": [],
"problems": [],
"wording": [],
"variant": {
"country": "DE",
"note": "Written and signed, with the signed document handed over; at least 50% of the last total pay, monthly, for up to 2 years; never with a minor.",
"sources": [
{
"url": "https://www.gesetze-im-internet.de/hgb/__74.html",
"article": "HGB §74 Abs. 1 und 2"
}
],
"confidence": "medium",
"last_reviewed": "2026-10-19",
"effective_from": "2000-01-01",
"effective_to": null,
"reviewed": false,
"fields": [
{
"name": "duration_months",
"type": "number",
"label": "How long after leaving",
"unit": "months",
"required": true,
"default": 12,
"values": null,
"min": 0,
"max": 60,
"hint": null
},
{
"name": "compensation_pct",
"type": "number",
"label": "Compensation, % of pay",
"unit": "percent",
"required": true,
"default": 50,
"values": null,
"min": 50,
"max": 100,
"hint": "At least half the last total pay, for each year of the restriction."
},
{
"name": "waiver",
"type": "enum",
"label": "Waiver",
"unit": null,
"required": true,
"default": "none",
"values": [
{
"value": "none",
"label": "No waiver"
},
{
"value": "mutual",
"label": "Only by agreement of both"
}
],
"min": null,
"max": null,
"hint": null
}
],
"rules": [
{
"id": "de.nc_pay",
"severity": "block",
"message": "In Germany the compensation is at least 50% of the last total pay (HGB §74(2)); below that the person is not bound.",
"field": "compensation_pct",
"source": {
"url": "https://www.gesetze-im-internet.de/hgb/__74.html",
"article": "HGB §74 Abs. 1 und 2"
},
"confidence": "medium"
}
],
"raises_to": {
"level": "qualified",
"confidence": "verified"
}
},
"documents": 3
}
}Archive a contract clause#
POST/v1/documents/clauses.archiveWrite
Archives one of your clauses (archived false restores it): new documents no longer use it (the starter for the country takes its place); documents made with it and its versions stay. Owners, admins and HR, in the web app.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_clauses_archiveon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
clause_idstringrequiredarchivedboolean
Returns
20 fields
idstringrequiredA company clause's id, or a starter's (builtin:clause.<country>.<type>).
source"builtin" | "company"requiredbuiltin: Bizisy's starter (copy it to change it); company: your own.
typestring (enum)requiredOne of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months.category"restrictions" | "start_and_end" | "pay_and_time" | "how_we_work" | "rights"requiredcountrystring (enum)requiredWhose rules it runs (EU: the EU minimum, for any other country).
One of:
PT,ES,FR,DE,IT,NL,EU.namestringrequiredlanguages"en" | "pt" | "es" | "fr" | "de" | "it"[]requiredstatus"draft" | "published" | "archived"requiredversionintegerrequiredThe latest published version (0: never published).
has_draftbooleanrequiredreviewedboolean | nullrequiredStarters: a local employment lawyer reviewed the text (false: not yet). null for your own.
builtin_fromstring | nullrequiredupdated_atstring | nullrequiredbodiesobjectrequired6 fields
enobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
ptobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
esobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
frobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
deobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
itobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
defaultsobjectrequiredYour defaults for its typed fields (HR changes them per document).
versionsobject[]required2 fields
versionintegerrequiredpublished_atstringrequired
problemsobject[]requiredLint warnings in the draft (errors are refused when saving).
8 fields
language"en" | "pt" | "es" | "fr" | "de" | "it"requiredfield"title" | "body"requiredlineintegerrequiredcolintegerrequiredcodestringrequiredmessagestringrequiredseverity"error" | "warning"requiredparamsobject
wordingobject[]requiredWording the rules forbid (pay secrecy, automatic termination, pay fines): blocks refuse publishing.
6 fields
rulestringrequiredmessagestringrequiredEnglish with {params}; the app translates it.
paramsobject | nullrequiredfieldstring | nullrequiredThe typed field it is about.
sourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"required
variantobjectrequiredThe law for its clause type and country: fields, rules, note and sources.
11 fields
countrystring (enum)requiredOne of:
PT,ES,FR,DE,IT,NL,EU.notestringrequiredWhat the law says here (English; the app translates it).
sourcesobject[]required2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requiredlast_reviewedstringrequiredeffective_fromstringrequiredeffective_tostring | nullrequiredreviewedbooleanrequiredfieldsobject[]required10 fields
namestringrequiredtype"number" | "text" | "boolean" | "enum" | "list" | "money"requiredlabelstringrequiredEnglish; the app translates it.
unitstring | nullrequiredrequiredbooleanrequireddefaultanyvaluesobject[] | nullrequired2 fields
valuestringrequiredlabelstringrequired
minnumber | nullrequiredmaxnumber | nullrequiredhintstring | nullrequired
rulesobject[]required6 fields
idstringrequiredseverity"block" | "warn"requiredmessagestringrequiredfieldstring | nullrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"required
raises_toobject | nullrequired2 fields
level"none" | "simple" | "advanced" | "qualified" | "wet"requiredconfidence"verified" | "medium" | "uncertain"required
documentsintegerrequiredDocuments made with it.
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/clauses.archive \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"clause_id":"cl1","archived":false}'const res = await fetch('https://api.bizisy.com/v1/documents/clauses.archive', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"clause_id": "cl1",
"archived": false
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/documents/clauses.archive",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"clause_id": "cl1",
"archived": False,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "cl1",
"source": "company",
"type": "non_compete",
"category": "restrictions",
"country": "DE",
"name": "Our non-compete (Germany)",
"languages": [
"de",
"en"
],
"status": "archived",
"version": 2,
"has_draft": true,
"reviewed": null,
"builtin_from": "builtin:clause.de.non_compete",
"updated_at": "2026-10-19T10:00:00.000Z",
"bodies": {
"de": {
"title": "Nachvertragliches Wettbewerbsverbot",
"body": "Für {{clause.duration_months}} Monate …"
},
"en": {
"title": "Post-contractual non-compete",
"body": "For {{clause.duration_months}} months …"
}
},
"defaults": {
"compensation_pct": 60
},
"versions": [
{
"version": 2,
"published_at": "2026-10-19T10:00:00.000Z"
},
{
"version": 1,
"published_at": "2026-10-18T10:00:00.000Z"
}
],
"problems": [],
"wording": [],
"variant": {
"country": "DE",
"note": "Written and signed, with the signed document handed over; at least 50% of the last total pay, monthly, for up to 2 years; never with a minor.",
"sources": [
{
"url": "https://www.gesetze-im-internet.de/hgb/__74.html",
"article": "HGB §74 Abs. 1 und 2"
}
],
"confidence": "medium",
"last_reviewed": "2026-10-19",
"effective_from": "2000-01-01",
"effective_to": null,
"reviewed": false,
"fields": [
{
"name": "duration_months",
"type": "number",
"label": "How long after leaving",
"unit": "months",
"required": true,
"default": 12,
"values": null,
"min": 0,
"max": 60,
"hint": null
},
{
"name": "compensation_pct",
"type": "number",
"label": "Compensation, % of pay",
"unit": "percent",
"required": true,
"default": 50,
"values": null,
"min": 50,
"max": 100,
"hint": "At least half the last total pay, for each year of the restriction."
},
{
"name": "waiver",
"type": "enum",
"label": "Waiver",
"unit": null,
"required": true,
"default": "none",
"values": [
{
"value": "none",
"label": "No waiver"
},
{
"value": "mutual",
"label": "Only by agreement of both"
}
],
"min": null,
"max": null,
"hint": null
}
],
"rules": [
{
"id": "de.nc_pay",
"severity": "block",
"message": "In Germany the compensation is at least 50% of the last total pay (HGB §74(2)); below that the person is not bound.",
"field": "compensation_pct",
"source": {
"url": "https://www.gesetze-im-internet.de/hgb/__74.html",
"article": "HGB §74 Abs. 1 und 2"
},
"confidence": "medium"
}
],
"raises_to": {
"level": "qualified",
"confidence": "verified"
}
},
"documents": 3
}
}Publish a contract clause#
POST/v1/documents/clauses.publishWrite
Publishes the draft of one of your clauses as a new version: from then on documents for people in its country use it instead of Bizisy's starter (when HR does not pick another). Published versions never change; each document records the clause and version it used. Refused with lint errors, with forbidden wording (pay secrecy, automatic termination, pay fines), or when nothing changed. Use dry_run to see the version it would make. At most 200 versions. Owners, admins and HR, in the web app.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_clauses_publishon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
clause_idstringrequired
Returns
21 fields
idstringrequiredA company clause's id, or a starter's (builtin:clause.<country>.<type>).
source"builtin" | "company"requiredbuiltin: Bizisy's starter (copy it to change it); company: your own.
typestring (enum)requiredOne of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months.category"restrictions" | "start_and_end" | "pay_and_time" | "how_we_work" | "rights"requiredcountrystring (enum)requiredWhose rules it runs (EU: the EU minimum, for any other country).
One of:
PT,ES,FR,DE,IT,NL,EU.namestringrequiredlanguages"en" | "pt" | "es" | "fr" | "de" | "it"[]requiredstatus"draft" | "published" | "archived"requiredversionintegerrequiredThe latest published version (0: never published).
has_draftbooleanrequiredreviewedboolean | nullrequiredStarters: a local employment lawyer reviewed the text (false: not yet). null for your own.
builtin_fromstring | nullrequiredupdated_atstring | nullrequiredbodiesobjectrequired6 fields
enobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
ptobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
esobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
frobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
deobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
itobject2 fields
titlestringrequiredThe clause's heading in the document.
1–120 characters.
bodystringrequiredMarkdown-lite paragraphs and lists (no headings), with {{clause.<field>}} for its typed fields, document fields such as {{employer.legal_name}}, and {{#if clause.<field> is <value>}}…{{/if}}.
Up to 8000 characters.
defaultsobjectrequiredYour defaults for its typed fields (HR changes them per document).
versionsobject[]required2 fields
versionintegerrequiredpublished_atstringrequired
problemsobject[]requiredLint warnings in the draft (errors are refused when saving).
8 fields
language"en" | "pt" | "es" | "fr" | "de" | "it"requiredfield"title" | "body"requiredlineintegerrequiredcolintegerrequiredcodestringrequiredmessagestringrequiredseverity"error" | "warning"requiredparamsobject
wordingobject[]requiredWording the rules forbid (pay secrecy, automatic termination, pay fines): blocks refuse publishing.
6 fields
rulestringrequiredmessagestringrequiredEnglish with {params}; the app translates it.
paramsobject | nullrequiredfieldstring | nullrequiredThe typed field it is about.
sourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"required
variantobjectrequiredThe law for its clause type and country: fields, rules, note and sources.
11 fields
countrystring (enum)requiredOne of:
PT,ES,FR,DE,IT,NL,EU.notestringrequiredWhat the law says here (English; the app translates it).
sourcesobject[]required2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requiredlast_reviewedstringrequiredeffective_fromstringrequiredeffective_tostring | nullrequiredreviewedbooleanrequiredfieldsobject[]required10 fields
namestringrequiredtype"number" | "text" | "boolean" | "enum" | "list" | "money"requiredlabelstringrequiredEnglish; the app translates it.
unitstring | nullrequiredrequiredbooleanrequireddefaultanyvaluesobject[] | nullrequired2 fields
valuestringrequiredlabelstringrequired
minnumber | nullrequiredmaxnumber | nullrequiredhintstring | nullrequired
rulesobject[]required6 fields
idstringrequiredseverity"block" | "warn"requiredmessagestringrequiredfieldstring | nullrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"required
raises_toobject | nullrequired2 fields
level"none" | "simple" | "advanced" | "qualified" | "wet"requiredconfidence"verified" | "medium" | "uncertain"required
documentsintegerrequiredDocuments made with it.
published_versionintegerrequired
Errors
validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/clauses.publish \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"clause_id":"cl1"}'const res = await fetch('https://api.bizisy.com/v1/documents/clauses.publish', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"clause_id": "cl1"
}),
});
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/documents/clauses.publish",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"clause_id": "cl1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "cl1",
"source": "company",
"type": "non_compete",
"category": "restrictions",
"country": "DE",
"name": "Our non-compete (Germany)",
"languages": [
"de",
"en"
],
"status": "published",
"version": 2,
"has_draft": false,
"reviewed": null,
"builtin_from": "builtin:clause.de.non_compete",
"updated_at": "2026-10-19T10:00:00.000Z",
"bodies": {
"de": {
"title": "Nachvertragliches Wettbewerbsverbot",
"body": "Für {{clause.duration_months}} Monate …"
},
"en": {
"title": "Post-contractual non-compete",
"body": "For {{clause.duration_months}} months …"
}
},
"defaults": {
"compensation_pct": 60
},
"versions": [
{
"version": 2,
"published_at": "2026-10-19T10:00:00.000Z"
},
{
"version": 1,
"published_at": "2026-10-18T10:00:00.000Z"
}
],
"problems": [],
"wording": [],
"variant": {
"country": "DE",
"note": "Written and signed, with the signed document handed over; at least 50% of the last total pay, monthly, for up to 2 years; never with a minor.",
"sources": [
{
"url": "https://www.gesetze-im-internet.de/hgb/__74.html",
"article": "HGB §74 Abs. 1 und 2"
}
],
"confidence": "medium",
"last_reviewed": "2026-10-19",
"effective_from": "2000-01-01",
"effective_to": null,
"reviewed": false,
"fields": [
{
"name": "duration_months",
"type": "number",
"label": "How long after leaving",
"unit": "months",
"required": true,
"default": 12,
"values": null,
"min": 0,
"max": 60,
"hint": null
},
{
"name": "compensation_pct",
"type": "number",
"label": "Compensation, % of pay",
"unit": "percent",
"required": true,
"default": 50,
"values": null,
"min": 50,
"max": 100,
"hint": "At least half the last total pay, for each year of the restriction."
},
{
"name": "waiver",
"type": "enum",
"label": "Waiver",
"unit": null,
"required": true,
"default": "none",
"values": [
{
"value": "none",
"label": "No waiver"
},
{
"value": "mutual",
"label": "Only by agreement of both"
}
],
"min": null,
"max": null,
"hint": null
}
],
"rules": [
{
"id": "de.nc_pay",
"severity": "block",
"message": "In Germany the compensation is at least 50% of the last total pay (HGB §74(2)); below that the person is not bound.",
"field": "compensation_pct",
"source": {
"url": "https://www.gesetze-im-internet.de/hgb/__74.html",
"article": "HGB §74 Abs. 1 und 2"
},
"confidence": "medium"
}
],
"raises_to": {
"level": "qualified",
"confidence": "verified"
}
},
"documents": 3,
"published_version": 2
}
}Preview a contract clause#
POST/v1/documents/clauses.previewRead
The clause as it appears in a document (HTML), filled for Bizisy's sample person (names with accents and other marks) with typed fields (yours, else its defaults), and the rules' result for its country: blocks, warnings, the signature level it raises a document to. From a clause (clause_id, optionally version; default its draft) or from a text you send (type, country, language, title, body: to preview while editing). context: the contract the rules assume (contract_type, term_days, part_time, is_minor, company_size). Also lint problems. Reads no person: API keys and AI assistants may use it. A starting point, not legal advice.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_clauses_previewon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
clause_idstringversionintegerAt least 1.
typestring (enum)One of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months.countrystringPattern
^[A-Z]{2}$.titlestringUp to 120 characters.
bodystringUp to 8000 characters.
language"en" | "pt" | "es" | "fr" | "de" | "it"Default: the clause country's language when written in it, else English, else its first.
fieldsobjectcontextobject5 fields
contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"term_daysintegerA fixed-term contract's length in days.
From 1 to 3650.
is_minorbooleanpart_timebooleancompany_sizeintegerFrom 1 to 1000000.
Returns
htmlstringrequiredlanguage"en" | "pt" | "es" | "fr" | "de" | "it"requiredproblemsobject[]required8 fields
language"en" | "pt" | "es" | "fr" | "de" | "it"requiredfield"title" | "body"requiredlineintegerrequiredcolintegerrequiredcodestringrequiredmessagestringrequiredseverity"error" | "warning"requiredparamsobject
checkobjectrequired7 fields
okbooleanrequiredNo block: the clause may go in the document.
countrystring (enum)requiredWhose rules ran: PT, ES, FR, DE, IT, NL, or EU (the EU minimum, for any other country).
One of:
PT,ES,FR,DE,IT,NL,EU.blocksobject[]requiredThe law Bizisy treats as settled is broken: the document is refused with it.
6 fields
rulestringrequiredmessagestringrequiredEnglish with {params}; the app translates it.
paramsobject | nullrequiredfieldstring | nullrequiredThe typed field it is about.
sourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"required
warnsobject[]requiredLess certain rules and reminders: the document is made, check with your lawyer.
6 fields
rulestringrequiredmessagestringrequiredEnglish with {params}; the app translates it.
paramsobject | nullrequiredfieldstring | nullrequiredThe typed field it is about.
sourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"required
raises_toobject | nullrequiredThe signature level the clause needs (e.g. a German non-compete: qualified or by hand).
3 fields
level"none" | "simple" | "advanced" | "qualified" | "wet"requiredconfidence"verified" | "medium" | "uncertain"requiredsourceobject | nullrequired2 fields
urlstringrequiredarticlestringrequired
tasksobject[]requiredTo do once signed (Italy: file the smart-working agreement within 5 days).
4 fields
idstringrequiredlabelstringrequireddays_after_startintegerrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
fieldsobjectrequiredThe fields as checked (defaults filled in).
variantobjectrequired11 fields
countrystring (enum)requiredOne of:
PT,ES,FR,DE,IT,NL,EU.notestringrequiredWhat the law says here (English; the app translates it).
sourcesobject[]required2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requiredlast_reviewedstringrequiredeffective_fromstringrequiredeffective_tostring | nullrequiredreviewedbooleanrequiredfieldsobject[]required10 fields
namestringrequiredtype"number" | "text" | "boolean" | "enum" | "list" | "money"requiredlabelstringrequiredEnglish; the app translates it.
unitstring | nullrequiredrequiredbooleanrequireddefaultanyvaluesobject[] | nullrequired2 fields
valuestringrequiredlabelstringrequired
minnumber | nullrequiredmaxnumber | nullrequiredhintstring | nullrequired
rulesobject[]required6 fields
idstringrequiredseverity"block" | "warn"requiredmessagestringrequiredfieldstring | nullrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"required
raises_toobject | nullrequired2 fields
level"none" | "simple" | "advanced" | "qualified" | "wet"requiredconfidence"verified" | "medium" | "uncertain"required
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/clauses.preview \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "probation",
"country": "NL",
"language": "en",
"title": "Probation",
"body": "{{clause.duration}}",
"fields": {
"duration": 1
},
"context": {
"contract_type": "fixed_term",
"term_days": 120,
"part_time": false,
"is_minor": false,
"company_size": 12
}
}'const res = await fetch('https://api.bizisy.com/v1/documents/clauses.preview', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"type": "probation",
"country": "NL",
"language": "en",
"title": "Probation",
"body": "{{clause.duration}}",
"fields": {
"duration": 1
},
"context": {
"contract_type": "fixed_term",
"term_days": 120,
"part_time": false,
"is_minor": false,
"company_size": 12
}
}),
});
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/documents/clauses.preview",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"type": "probation",
"country": "NL",
"language": "en",
"title": "Probation",
"body": "{{clause.duration}}",
"fields": {
"duration": 1,
},
"context": {
"contract_type": "fixed_term",
"term_days": 120,
"part_time": False,
"is_minor": False,
"company_size": 12,
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"html": "<!doctype html><html lang=\"de\"><body>…</body></html>",
"language": "en",
"problems": [],
"check": {
"ok": false,
"country": "DE",
"blocks": [
{
"rule": "de.nc_pay",
"message": "In Germany the compensation is at least 50% of the last total pay (HGB §74(2)); below that the person is not bound.",
"params": {
"pct": 40
},
"field": "compensation_pct",
"source": {
"url": "https://www.gesetze-im-internet.de/hgb/__74.html",
"article": "HGB §74 Abs. 1 und 2"
},
"confidence": "medium"
}
],
"warns": [],
"raises_to": {
"level": "qualified",
"confidence": "verified",
"source": {
"url": "https://www.gesetze-im-internet.de/bgb/__126a.html",
"article": "HGB §74 Abs. 1; BGB §§126, 126a"
}
},
"tasks": [],
"fields": {
"duration_months": 12,
"compensation_pct": 40,
"waiver": "none"
}
},
"variant": {
"country": "DE",
"note": "Written and signed, with the signed document handed over; at least 50% of the last total pay, monthly, for up to 2 years; never with a minor.",
"sources": [
{
"url": "https://www.gesetze-im-internet.de/hgb/__74.html",
"article": "HGB §74 Abs. 1 und 2"
}
],
"confidence": "medium",
"last_reviewed": "2026-10-19",
"effective_from": "2000-01-01",
"effective_to": null,
"reviewed": false,
"fields": [
{
"name": "duration_months",
"type": "number",
"label": "How long after leaving",
"unit": "months",
"required": true,
"default": 12,
"values": null,
"min": 0,
"max": 60,
"hint": null
},
{
"name": "compensation_pct",
"type": "number",
"label": "Compensation, % of pay",
"unit": "percent",
"required": true,
"default": 50,
"values": null,
"min": 50,
"max": 100,
"hint": "At least half the last total pay, for each year of the restriction."
},
{
"name": "waiver",
"type": "enum",
"label": "Waiver",
"unit": null,
"required": true,
"default": "none",
"values": [
{
"value": "none",
"label": "No waiver"
},
{
"value": "mutual",
"label": "Only by agreement of both"
}
],
"min": null,
"max": null,
"hint": null
}
],
"rules": [
{
"id": "de.nc_pay",
"severity": "block",
"message": "In Germany the compensation is at least 50% of the last total pay (HGB §74(2)); below that the person is not bound.",
"field": "compensation_pct",
"source": {
"url": "https://www.gesetze-im-internet.de/hgb/__74.html",
"article": "HGB §74 Abs. 1 und 2"
},
"confidence": "medium"
}
],
"raises_to": {
"level": "qualified",
"confidence": "verified"
}
}
}
}Check a contract clause against the law#
POST/v1/documents/clauses.checkRead
Runs a clause type's rules for a country (any 2-letter code: its rules, or the EU minimum) on typed fields, without saving: blocks (the law Bizisy treats as settled: a document with it is refused), warnings (less certain rules, reminders), the signature level it raises a document to, tasks to do once signed, and the fields as checked (defaults filled in). Optionally the clause text (forbidden wording: pay secrecy, automatic termination, pay fines) and the contract (context). Pure: reads nothing. API keys and AI assistants may use it. A starting point, not legal advice.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_clauses_checkon HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
typestring (enum)requiredOne of:
non_compete,non_solicitation,probation,training_repayment,remote_work,exclusivity,confidentiality,ip_inventions,mobility,overtime_included,notice,garden_leave,equipment,monitoring_notice,collective_agreement,pay_extra_months.countrystringrequiredPattern
^[A-Z]{2}$.fieldsobjectcontextobject5 fields
contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"term_daysintegerA fixed-term contract's length in days.
From 1 to 3650.
is_minorbooleanpart_timebooleancompany_sizeintegerFrom 1 to 1000000.
textstringUp to 8000 characters.
Returns
8 fields
okbooleanrequiredNo block: the clause may go in the document.
countrystring (enum)requiredWhose rules ran: PT, ES, FR, DE, IT, NL, or EU (the EU minimum, for any other country).
One of:
PT,ES,FR,DE,IT,NL,EU.blocksobject[]requiredThe law Bizisy treats as settled is broken: the document is refused with it.
6 fields
rulestringrequiredmessagestringrequiredEnglish with {params}; the app translates it.
paramsobject | nullrequiredfieldstring | nullrequiredThe typed field it is about.
sourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"required
warnsobject[]requiredLess certain rules and reminders: the document is made, check with your lawyer.
6 fields
rulestringrequiredmessagestringrequiredEnglish with {params}; the app translates it.
paramsobject | nullrequiredfieldstring | nullrequiredThe typed field it is about.
sourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"required
raises_toobject | nullrequiredThe signature level the clause needs (e.g. a German non-compete: qualified or by hand).
3 fields
level"none" | "simple" | "advanced" | "qualified" | "wet"requiredconfidence"verified" | "medium" | "uncertain"requiredsourceobject | nullrequired2 fields
urlstringrequiredarticlestringrequired
tasksobject[]requiredTo do once signed (Italy: file the smart-working agreement within 5 days).
4 fields
idstringrequiredlabelstringrequireddays_after_startintegerrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
fieldsobjectrequiredThe fields as checked (defaults filled in).
variantobjectrequired11 fields
countrystring (enum)requiredOne of:
PT,ES,FR,DE,IT,NL,EU.notestringrequiredWhat the law says here (English; the app translates it).
sourcesobject[]required2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"requiredlast_reviewedstringrequiredeffective_fromstringrequiredeffective_tostring | nullrequiredreviewedbooleanrequiredfieldsobject[]required10 fields
namestringrequiredtype"number" | "text" | "boolean" | "enum" | "list" | "money"requiredlabelstringrequiredEnglish; the app translates it.
unitstring | nullrequiredrequiredbooleanrequireddefaultanyvaluesobject[] | nullrequired2 fields
valuestringrequiredlabelstringrequired
minnumber | nullrequiredmaxnumber | nullrequiredhintstring | nullrequired
rulesobject[]required6 fields
idstringrequiredseverity"block" | "warn"requiredmessagestringrequiredfieldstring | nullrequiredsourceobjectrequired2 fields
urlstringrequiredarticlestringrequired
confidence"verified" | "medium" | "uncertain"required
raises_toobject | nullrequired2 fields
level"none" | "simple" | "advanced" | "qualified" | "wet"requiredconfidence"verified" | "medium" | "uncertain"required
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/clauses.check \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "exclusivity",
"country": "FR",
"context": {
"part_time": true
},
"text": "Le salarié…"
}'const res = await fetch('https://api.bizisy.com/v1/documents/clauses.check', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"type": "exclusivity",
"country": "FR",
"context": {
"part_time": true
},
"text": "Le salarié…"
}),
});
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/documents/clauses.check",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"type": "exclusivity",
"country": "FR",
"context": {
"part_time": True,
},
"text": "Le salarié…",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"ok": false,
"country": "FR",
"blocks": [
{
"rule": "de.nc_pay",
"message": "In Germany the compensation is at least 50% of the last total pay (HGB §74(2)); below that the person is not bound.",
"params": {
"pct": 40
},
"field": "compensation_pct",
"source": {
"url": "https://www.gesetze-im-internet.de/hgb/__74.html",
"article": "HGB §74 Abs. 1 und 2"
},
"confidence": "medium"
}
],
"warns": [],
"raises_to": {
"level": "qualified",
"confidence": "verified",
"source": {
"url": "https://www.gesetze-im-internet.de/bgb/__126a.html",
"article": "HGB §74 Abs. 1; BGB §§126, 126a"
}
},
"tasks": [],
"fields": {
"duration_months": 12,
"compensation_pct": 40,
"waiver": "none"
},
"variant": {
"country": "DE",
"note": "Written and signed, with the signed document handed over; at least 50% of the last total pay, monthly, for up to 2 years; never with a minor.",
"sources": [
{
"url": "https://www.gesetze-im-internet.de/hgb/__74.html",
"article": "HGB §74 Abs. 1 und 2"
}
],
"confidence": "medium",
"last_reviewed": "2026-10-19",
"effective_from": "2000-01-01",
"effective_to": null,
"reviewed": false,
"fields": [
{
"name": "duration_months",
"type": "number",
"label": "How long after leaving",
"unit": "months",
"required": true,
"default": 12,
"values": null,
"min": 0,
"max": 60,
"hint": null
},
{
"name": "compensation_pct",
"type": "number",
"label": "Compensation, % of pay",
"unit": "percent",
"required": true,
"default": 50,
"values": null,
"min": 50,
"max": 100,
"hint": "At least half the last total pay, for each year of the restriction."
},
{
"name": "waiver",
"type": "enum",
"label": "Waiver",
"unit": null,
"required": true,
"default": "none",
"values": [
{
"value": "none",
"label": "No waiver"
},
{
"value": "mutual",
"label": "Only by agreement of both"
}
],
"min": null,
"max": null,
"hint": null
}
],
"rules": [
{
"id": "de.nc_pay",
"severity": "block",
"message": "In Germany the compensation is at least 50% of the last total pay (HGB §74(2)); below that the person is not bound.",
"field": "compensation_pct",
"source": {
"url": "https://www.gesetze-im-internet.de/hgb/__74.html",
"article": "HGB §74 Abs. 1 und 2"
},
"confidence": "medium"
}
],
"raises_to": {
"level": "qualified",
"confidence": "verified"
}
}
}
}List employment contracts#
POST/v1/documents/contracts.listRead
Documents → Contracts: one row per person employed today or starting later, with their current employment contract — made from a contract template (open-ended, fixed-term, part-time) or a file uploaded in the Contract category — and its status: to_review (a draft only HR sees: review and send it with documents_prepared_decide), waiting (out for signature: who signs next), signed, not_signed (shared without a signature, or the request was declined, expired or canceled), uploaded, or missing (no contract in Bizisy: create one with documents_generate or upload the signed copy). Each with the contract type, country and term org records, how many amendments are on file and whether one waits for review, and a fixed-term contract's end-of-term notice waiting for a decision. Filters: status, type (a contract type), country, ending_within_days (fixed-term contracts ending in that many days or less; 60 for "ending soon"), q (words in the name), person_id. Counts are for every row before filters. Owners, admins and HR only; a person never sees their own draft here. Through API keys and AI assistants: no names of who signs next.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_contracts_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
status"to_review" | "waiting" | "signed" | "not_signed" | "uploaded" | "missing"typestringUp to 40 characters.
countrystringPattern
^[A-Z]{2}$.ending_within_daysintegerFrom 0 to 366.
qstringUp to 100 characters.
person_idstring
Returns
contractsobject[]required19 fields
personobjectrequired2 fields
idstringrequirednamestringrequired
status"to_review" | "waiting" | "signed" | "not_signed" | "uploaded" | "missing"requiredto_review: a draft only HR sees (send it from
documents_prepared_decide); waiting: out for signature; signed: everyone signed; not_signed: made and shared without a signature, or the request was declined, expired or canceled; uploaded: a file in the Contract category; missing: no contract in Bizisy.employment"active" | "pre_hire"requiredEmployed today, or starting later.
typestring | nullrequiredThe contract type org records (permanent, fixed_term, temporary, internship, freelance); null when not recorded.
part_timebooleanrequiredcountrystring | nullrequiredThe country whose law applies (their employer's, else their location's).
titlestring | nullrequiredstartstring | nullrequiredThe first day of their current employment.
endstring | nullrequiredThe contract end date (fixed-term).
ends_in_daysinteger | nullrequireddocumentobject | nullrequiredTheir current contract document (the newest); null when missing.
9 fields
idstringrequiredtitlestringrequiredcategorystringrequiredsource"template" | "upload"requiredtemplate: made from a document template; upload: a file HR uploaded.
kindstring (enum)requiredThe template's kind (null for uploads).
One of:
contract_open,contract_fixed,contract_part_time,statement,amendment,change_notice,end_notice,certificate,declaration,policy,letter,offer_letter,pay_review_letter.template_idstring | nullrequiredversioninteger | nullrequiredlanguagestring | nullrequiredcreated_atstringrequired
prepared_idstring | nullrequiredto_review: the prepared document to review and send.
signatureobject | nullrequired9 fields
idstringrequiredstatusstring (enum)requiredOne of:
queued,sending,ongoing,done,declined,expired,canceled,failed.level"simple" | "advanced" | "qualified"requiredsignedintegerrequiredtotalintegerrequirednextobject | nullrequiredWho signs next (open requests only).
3 fields
role"person" | "manager" | "me" | "other"requiredperson: the person the document is about; manager: their manager; me: the HR member who sent it (the employer); other.
namestring | nullrequirednull through API keys and AI assistants, and once erased.
youbooleanrequiredIt is your turn to sign.
sent_atstring | nullrequiredcompleted_atstring | nullrequiredexpires_onstringrequired
signed_atstring | nullrequiredsigned_document_idstring | nullrequiredamendmentsobjectrequired3 fields
countintegerrequiredAmendments and addenda on file.
to_reviewstring | nullrequiredAn amendment Bizisy prepared waiting for HR: its prepared id.
documentsobject[]requiredThe amendments and addenda on file, newest first.
9 fields
idstringrequiredtitlestringrequiredcategorystringrequiredsource"template" | "upload"requiredtemplate: made from a document template; upload: a file HR uploaded.
kindstring (enum)requiredThe template's kind (null for uploads).
One of:
contract_open,contract_fixed,contract_part_time,statement,amendment,change_notice,end_notice,certificate,declaration,policy,letter,offer_letter,pay_review_letter.template_idstring | nullrequiredversioninteger | nullrequiredlanguagestring | nullrequiredcreated_atstringrequired
end_noticeobject | nullrequiredA fixed-term contract's end-of-term notice waiting for HR: decide renew, open-ended or end (
documents_prepared_contract) before sending.2 fields
prepared_idstringrequireddecidedbooleanrequired
versionsintegerrequiredContract documents on file for them (the current one and earlier ones).
earlierobject[]requiredTheir earlier contract documents, newest first.
9 fields
idstringrequiredtitlestringrequiredcategorystringrequiredsource"template" | "upload"requiredtemplate: made from a document template; upload: a file HR uploaded.
kindstring (enum)requiredThe template's kind (null for uploads).
One of:
contract_open,contract_fixed,contract_part_time,statement,amendment,change_notice,end_notice,certificate,declaration,policy,letter,offer_letter,pay_review_letter.template_idstring | nullrequiredversioninteger | nullrequiredlanguagestring | nullrequiredcreated_atstringrequired
countsobjectrequired7 fields
allintegerrequiredto_reviewintegerrequiredwaitingintegerrequiredsignedintegerrequiredmissingintegerrequiredending_soonintegerrequiredamendments_to_reviewintegerrequired
typesstring[]requiredThe contract types in use (for a filter).
countriesstring[]requiredThe countries in use (for a filter).
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/contracts.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"type":"fixed_term","country":"PT","ending_within_days":60,"q":"ana"}'const res = await fetch('https://api.bizisy.com/v1/documents/contracts.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"type": "fixed_term",
"country": "PT",
"ending_within_days": 60,
"q": "ana"
}),
});
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/documents/contracts.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"type": "fixed_term",
"country": "PT",
"ending_within_days": 60,
"q": "ana",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"contracts": [
{
"person": {
"id": "p1",
"name": "Ana Ferreira"
},
"status": "waiting",
"employment": "active",
"type": "fixed_term",
"part_time": false,
"country": "PT",
"title": "Designer",
"start": "2026-03-02",
"end": "2027-03-01",
"ends_in_days": 132,
"document": {
"id": "d1",
"title": "Contrato a termo certo – Ana Ferreira",
"category": "Contract",
"source": "template",
"kind": "contract_fixed",
"template_id": "builtin:pt.contract_fixed",
"version": 1,
"language": "pt",
"created_at": "2026-10-14T09:00:00.000Z"
},
"prepared_id": null,
"signature": {
"id": "sig1",
"status": "ongoing",
"level": "qualified",
"signed": 1,
"total": 2,
"next": {
"role": "me",
"name": "Marta Rocha",
"you": false
},
"sent_at": "2026-10-14T09:00:00.000Z",
"completed_at": null,
"expires_on": "2026-11-13"
},
"signed_at": null,
"signed_document_id": null,
"end_notice": null,
"versions": 1,
"earlier": [],
"amendments": {
"count": 1,
"to_review": "prep7",
"documents": [
{
"id": "d5",
"title": "Aditamento – Ana Ferreira",
"category": "Addendum",
"source": "upload",
"kind": null,
"template_id": null,
"version": null,
"language": null,
"created_at": "2026-06-01T09:00:00.000Z"
}
]
}
},
{
"person": {
"id": "p2",
"name": "Rita Lopes"
},
"status": "missing",
"employment": "active",
"type": null,
"part_time": false,
"country": "PT",
"title": "Designer",
"start": "2026-03-02",
"end": null,
"ends_in_days": null,
"document": null,
"prepared_id": null,
"signature": null,
"signed_at": null,
"signed_document_id": null,
"end_notice": null,
"versions": 0,
"earlier": [],
"amendments": {
"count": 0,
"to_review": null,
"documents": []
}
}
],
"counts": {
"all": 2,
"to_review": 0,
"waiting": 1,
"signed": 0,
"missing": 1,
"ending_soon": 0,
"amendments_to_review": 1
},
"types": [
"fixed_term"
],
"countries": [
"PT"
]
}
}List letters and certificates#
POST/v1/documents/letters.listRead
Documents → Letters & certificates: written statements of working conditions, change notices, end-of-term notices, work certificates, employment and salary declarations, letters made from templates and signed offer letters, newest first after what waits for HR. status: to_review (prepared by Bizisy or drafted from a template, only HR sees it: documents_prepared_get, documents_prepared_decide), requested (the person asked for it in My workspace), waiting (out for signature), signed, sent (it reached the person; proof of delivery in documents_prepared_list), accepted (a signed offer letter from Hiring). Filters: status (sent also lists signed and accepted ones), kind, person_id. Sent prepared documents of the last 365 days. Owners, admins and HR only; a person never sees their own draft here. Through API keys and AI assistants: no reasons and no names of who signs next.
- Who can call it
- Manage key owner admin hr
- MCP tool
documents_letters_liston HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
status"to_review" | "requested" | "waiting" | "signed" | "sent" | "accepted"kindstring (enum)One of:
contract_open,contract_fixed,contract_part_time,statement,amendment,change_notice,end_notice,certificate,declaration,policy,letter,offer_letter,pay_review_letter.person_idstring
Returns
lettersobject[]required14 fields
idstringrequiredThe prepared document's id (prep_…) when Bizisy prepared it, else the document's.
personobjectrequired2 fields
idstringrequirednamestringrequired
kindstring (enum)requiredstatement, change_notice, end_notice, certificate, declaration, letter, offer_letter or pay_review_letter.
One of:
contract_open,contract_fixed,contract_part_time,statement,amendment,change_notice,end_notice,certificate,declaration,policy,letter,offer_letter,pay_review_letter.variant"renewal" | "reference" | "salary" | "employment"requiredstatus"to_review" | "requested" | "waiting" | "signed" | "sent" | "accepted"requiredto_review: waiting for HR (only HR sees it); requested: the person asked for it in My workspace and it waits for HR; waiting: out for signature; signed; sent: it reached the person; accepted: a signed offer letter.
source"prepared" | "template" | "offer"requiredreasonstring (enum)requiredWhy Bizisy prepared it (null for others). Null through API keys and AI assistants.
One of:
hire,rehire,change,request,current_staff,manual,bulk,fixed_term_end,leaving,pay_review.prepared_idstring | nullrequireddocument_idstring | nullrequireddue_onstring | nullrequiredThe legal deadline to give it (prepared ones).
overduebooleanrequireddatestringrequiredWhen it was sent, signed or made (YYYY-MM-DD).
signatureobject | nullrequired9 fields
idstringrequiredstatusstring (enum)requiredOne of:
queued,sending,ongoing,done,declined,expired,canceled,failed.level"simple" | "advanced" | "qualified"requiredsignedintegerrequiredtotalintegerrequirednextobject | nullrequiredWho signs next (open requests only).
3 fields
role"person" | "manager" | "me" | "other"requiredperson: the person the document is about; manager: their manager; me: the HR member who sent it (the employer); other.
namestring | nullrequirednull through API keys and AI assistants, and once erased.
youbooleanrequiredIt is your turn to sign.
sent_atstring | nullrequiredcompleted_atstring | nullrequiredexpires_onstringrequired
decidedboolean | nullrequiredEnd-of-term notices: whether HR decided the contract (null for others).
countsobjectrequired5 fields
allintegerrequiredto_reviewintegerrequiredrequestedintegerrequiredwaitingintegerrequiredsentintegerrequired
Errors
validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal
curl https://api.bizisy.com/v1/documents/letters.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"kind":"certificate","person_id":"p1"}'const res = await fetch('https://api.bizisy.com/v1/documents/letters.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"kind": "certificate",
"person_id": "p1"
}),
});
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/documents/letters.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"kind": "certificate",
"person_id": "p1",
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"letters": [
{
"id": "prep1",
"person": {
"id": "p1",
"name": "Ana Ferreira"
},
"kind": "statement",
"variant": null,
"status": "to_review",
"source": "prepared",
"reason": "hire",
"prepared_id": "prep1",
"document_id": null,
"due_on": "2026-10-27",
"overdue": false,
"date": "2026-10-20",
"signature": null,
"decided": null
},
{
"id": "d9",
"person": {
"id": "p1",
"name": "Ana Ferreira"
},
"kind": "offer_letter",
"variant": null,
"status": "accepted",
"source": "offer",
"reason": null,
"prepared_id": null,
"document_id": "d9",
"due_on": null,
"overdue": false,
"date": "2026-10-20",
"signature": null,
"decided": null
}
],
"counts": {
"all": 2,
"to_review": 1,
"requested": 0,
"waiting": 0,
"sent": 1
}
}
}Something missing or wrong on this page? Write to hello@bizisy.com.