Skip to content

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_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • person_idstring
  • scope"person" | "company" | "all"

    Default all (person_id implies person).

  • categorystring

    Up to 60 characters.

  • qstring

    Words 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"
  • limitinteger

    Default 500.

    From 1 to 500.

Returns

  • documentsobject[]required
    19 fields
    • idstringrequired
    • titlestringrequired
    • categorystringrequired
    • subjectobjectrequired
      3 fields (one of several shapes)

      Option 1

      • kind"person"required
      • personobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired

      Option 2

      • kind"company"required
    • visibilitystring (enum)required

      One of: hr, hr_person, hr_person_manager, everyone, managers, hr, accountant.

    • uploaded_by"hr" | "self"required

      self: the person added it themself ("From me", or a custom field they fill in).

    • fieldobject | nullrequired

      A custom file field's file (org_fields_list): its visibility follows the field's tier; replace or remove it through the field.

      2 fields
      • keystringrequired
      • labelstringrequired
    • expires_onstring | nullrequired
    • notesstring | nullrequired

      null when you only see metadata.

    • fileobjectrequired
      4 fields
      • namestring | nullrequired

        The original file name; null when you only see metadata.

      • sizeintegerrequired
      • content_typestringrequired
      • previewablebooleanrequired

        The web app can show it (PDF, PNG, JPEG, WebP).

    • access"full" | "metadata"required

      metadata: 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 | nullrequired

      A signed copy or signature audit trail the e-signature tool handed back: the original document. null for other documents.

      2 fields
      • document_idstringrequired
      • kind"signed" | "audit_trail"required
    • signatureobject | null

      The latest signature request (lists only): status, level and how many have signed.

      6 fields
      • idstringrequired
      • statusstring (enum)required

        One of: queued, sending, ongoing, done, declined, expired, canceled, failed.

      • level"simple" | "advanced" | "qualified"required
      • signedintegerrequired
      • totalintegerrequired
      • your_turnbooleanrequired

        You are the signer the e-signature tool is waiting for (check your email from it).

    • generated_fromobject | null

      Made from a document template: which one, its version, language and style (documents_templates_get). null for uploaded documents.

      4 fields
      • template_idstringrequired
      • versionintegerrequired
      • languagestringrequired
      • style"international" | "continental"required

        The document style it was made in (international or continental); null for documents made before styles existed.

    • draftobject | null

      A 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_idstringrequired
      • visibility"hr" | "hr_person" | "hr_person_manager"required
    • deliveryobject | null

      Proof 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"required
      • sent_atstringrequired
      • opened_atstring | nullrequired
      • acknowledged_atstring | nullrequired
      • handed_over_onstring | nullrequired
    • status"pending" | "ready"required
    • created_atstringrequired
    • updated_atstringrequired
  • categoriesstring[]required

    Every category in use for new documents: the starter list and your own.

  • max_file_bytesintegerrequired

    The largest file allowed (Settings → Storage).

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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
}'
Response
{
  "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_start on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • subjectobjectrequired
    3 fields (one of several shapes)

    Option 1

    • kind"person"required
    • person_idstringrequired

    Option 2

    • kind"company"required
  • categorystringrequired

    1–40 characters.

  • titlestring

    Up to 200 characters.

  • visibilitystring (enum)

    One of: hr, hr_person, hr_person_manager, everyone, managers, hr, accountant.

  • expires_onstring | null

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

  • notesstring | null

    Up to 2000 characters.

  • notify_personboolean

    A 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.

  • fileobjectrequired
    4 fields
    • namestringrequired

      The file name, e.g. "Contract 2026.pdf" (kept as metadata only).

      1–500 characters.

    • sizeintegerrequired

      Bytes. Must equal what is uploaded.

      At least 0.

    • content_typestringrequired

      application/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.

    • sha256stringrequired

      Lowercase hex SHA-256 of the file; checked against the upload.

      Pattern ^[0-9a-f]{64}$.

Returns

  • documentobjectrequired
    19 fields
    • idstringrequired
    • titlestringrequired
    • categorystringrequired
    • subjectobjectrequired
      3 fields (one of several shapes)

      Option 1

      • kind"person"required
      • personobject | nullrequired
        2 fields
        • idstringrequired
        • namestringrequired

      Option 2

      • kind"company"required
    • visibilitystring (enum)required

      One of: hr, hr_person, hr_person_manager, everyone, managers, hr, accountant.

    • uploaded_by"hr" | "self"required

      self: the person added it themself ("From me", or a custom field they fill in).

    • fieldobject | nullrequired

      A custom file field's file (org_fields_list): its visibility follows the field's tier; replace or remove it through the field.

      2 fields
      • keystringrequired
      • labelstringrequired
    • expires_onstring | nullrequired
    • notesstring | nullrequired

      null when you only see metadata.

    • fileobjectrequired
      4 fields
      • namestring | nullrequired

        The original file name; null when you only see metadata.

      • sizeintegerrequired
      • content_typestringrequired
      • previewablebooleanrequired

        The web app can show it (PDF, PNG, JPEG, WebP).

    • access"full" | "metadata"required

      metadata: 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 | nullrequired

      A signed copy or signature audit trail the e-signature tool handed back: the original document. null for other documents.

      2 fields
      • document_idstringrequired
      • kind"signed" | "audit_trail"required
    • signatureobject | null

      The latest signature request (lists only): status, level and how many have signed.

      6 fields
      • idstringrequired
      • statusstring (enum)required

        One of: queued, sending, ongoing, done, declined, expired, canceled, failed.

      • level"simple" | "advanced" | "qualified"required
      • signedintegerrequired
      • totalintegerrequired
      • your_turnbooleanrequired

        You are the signer the e-signature tool is waiting for (check your email from it).

    • generated_fromobject | null

      Made from a document template: which one, its version, language and style (documents_templates_get). null for uploaded documents.

      4 fields
      • template_idstringrequired
      • versionintegerrequired
      • languagestringrequired
      • style"international" | "continental"required

        The document style it was made in (international or continental); null for documents made before styles existed.

    • draftobject | null

      A 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_idstringrequired
      • visibility"hr" | "hr_person" | "hr_person_manager"required
    • deliveryobject | null

      Proof 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"required
      • sent_atstringrequired
      • opened_atstring | nullrequired
      • acknowledged_atstring | nullrequired
      • handed_over_onstring | nullrequired
    • status"pending" | "ready"required
    • created_atstringrequired
    • updated_atstringrequired
  • uploadobject | nullrequired

    null on a dry run.

    4 fields
    • urlstringrequired

      Short-lived signed URL (15 minutes). Never share it.

    • method"PUT"required
    • headersobjectrequired

      Send exactly these headers (they include the exact file size: any other size is refused).

    • resumablefalserequired

      Always 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
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"
  }
}'
Response
{
  "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_finish on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • document_idstringrequired

Returns

19 fields
  • idstringrequired
  • titlestringrequired
  • categorystringrequired
  • subjectobjectrequired
    3 fields (one of several shapes)

    Option 1

    • kind"person"required
    • personobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired

    Option 2

    • kind"company"required
  • visibilitystring (enum)required

    One of: hr, hr_person, hr_person_manager, everyone, managers, hr, accountant.

  • uploaded_by"hr" | "self"required

    self: the person added it themself ("From me", or a custom field they fill in).

  • fieldobject | nullrequired

    A custom file field's file (org_fields_list): its visibility follows the field's tier; replace or remove it through the field.

    2 fields
    • keystringrequired
    • labelstringrequired
  • expires_onstring | nullrequired
  • notesstring | nullrequired

    null when you only see metadata.

  • fileobjectrequired
    4 fields
    • namestring | nullrequired

      The original file name; null when you only see metadata.

    • sizeintegerrequired
    • content_typestringrequired
    • previewablebooleanrequired

      The web app can show it (PDF, PNG, JPEG, WebP).

  • access"full" | "metadata"required

    metadata: 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 | nullrequired

    A signed copy or signature audit trail the e-signature tool handed back: the original document. null for other documents.

    2 fields
    • document_idstringrequired
    • kind"signed" | "audit_trail"required
  • signatureobject | null

    The latest signature request (lists only): status, level and how many have signed.

    6 fields
    • idstringrequired
    • statusstring (enum)required

      One of: queued, sending, ongoing, done, declined, expired, canceled, failed.

    • level"simple" | "advanced" | "qualified"required
    • signedintegerrequired
    • totalintegerrequired
    • your_turnbooleanrequired

      You are the signer the e-signature tool is waiting for (check your email from it).

  • generated_fromobject | null

    Made from a document template: which one, its version, language and style (documents_templates_get). null for uploaded documents.

    4 fields
    • template_idstringrequired
    • versionintegerrequired
    • languagestringrequired
    • style"international" | "continental"required

      The document style it was made in (international or continental); null for documents made before styles existed.

  • draftobject | null

    A 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_idstringrequired
    • visibility"hr" | "hr_person" | "hr_person_manager"required
  • deliveryobject | null

    Proof 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"required
    • sent_atstringrequired
    • opened_atstring | nullrequired
    • acknowledged_atstring | nullrequired
    • handed_over_onstring | nullrequired
  • status"pending" | "ready"required
  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_update on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • document_idstringrequired
  • titlestring

    1–200 characters.

  • categorystring

    1–40 characters.

  • visibilitystring (enum)

    One of: hr, hr_person, hr_person_manager, everyone, managers, hr, accountant.

  • expires_onstring | null

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

  • notesstring | null

    Up to 2000 characters.

  • notify_personboolean

    When 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
  • idstringrequired
  • titlestringrequired
  • categorystringrequired
  • subjectobjectrequired
    3 fields (one of several shapes)

    Option 1

    • kind"person"required
    • personobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired

    Option 2

    • kind"company"required
  • visibilitystring (enum)required

    One of: hr, hr_person, hr_person_manager, everyone, managers, hr, accountant.

  • uploaded_by"hr" | "self"required

    self: the person added it themself ("From me", or a custom field they fill in).

  • fieldobject | nullrequired

    A custom file field's file (org_fields_list): its visibility follows the field's tier; replace or remove it through the field.

    2 fields
    • keystringrequired
    • labelstringrequired
  • expires_onstring | nullrequired
  • notesstring | nullrequired

    null when you only see metadata.

  • fileobjectrequired
    4 fields
    • namestring | nullrequired

      The original file name; null when you only see metadata.

    • sizeintegerrequired
    • content_typestringrequired
    • previewablebooleanrequired

      The web app can show it (PDF, PNG, JPEG, WebP).

  • access"full" | "metadata"required

    metadata: 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 | nullrequired

    A signed copy or signature audit trail the e-signature tool handed back: the original document. null for other documents.

    2 fields
    • document_idstringrequired
    • kind"signed" | "audit_trail"required
  • signatureobject | null

    The latest signature request (lists only): status, level and how many have signed.

    6 fields
    • idstringrequired
    • statusstring (enum)required

      One of: queued, sending, ongoing, done, declined, expired, canceled, failed.

    • level"simple" | "advanced" | "qualified"required
    • signedintegerrequired
    • totalintegerrequired
    • your_turnbooleanrequired

      You are the signer the e-signature tool is waiting for (check your email from it).

  • generated_fromobject | null

    Made from a document template: which one, its version, language and style (documents_templates_get). null for uploaded documents.

    4 fields
    • template_idstringrequired
    • versionintegerrequired
    • languagestringrequired
    • style"international" | "continental"required

      The document style it was made in (international or continental); null for documents made before styles existed.

  • draftobject | null

    A 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_idstringrequired
    • visibility"hr" | "hr_person" | "hr_person_manager"required
  • deliveryobject | null

    Proof 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"required
    • sent_atstringrequired
    • opened_atstring | nullrequired
    • acknowledged_atstring | nullrequired
    • handed_over_onstring | nullrequired
  • status"pending" | "ready"required
  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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
}'
Response
{
  "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_delete on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • document_idstringrequired

Returns

  • idstringrequired
  • deletedtruerequired
  • categorystringrequired
  • person_idstring | nullrequired
  • visibilitystringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_download on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • document_idstringrequired

Returns

8 fields
  • urlstring | nullrequired

    Signed URL valid for 5 minutes, downloads as an attachment. null on a dry run. Never store or share it.

  • expires_atstring | nullrequired
  • file_namestringrequired
  • content_typestringrequired
  • sizeintegerrequired
  • categorystringrequired
  • person_idstring | nullrequired
  • visibilitystringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_get on HR Assistant, My Workplace
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • starterstring[]required
  • customstring[]required

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/documents/categories.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "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_set on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • customstring[]required

    1–40 characters. Up to 30 items.

Returns

  • starterstring[]required
  • customstring[]required

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"]}'
Response
{
  "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_create on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • person_idstringrequired
  • categorystringrequired

    1–40 characters.

  • due_onstring | null

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

  • notestring | null

    Up to 300 characters.

Returns

11 fields
  • idstringrequired
  • personobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • categorystringrequired
  • notestring | nullrequired
  • due_onstring | nullrequired
  • status"open" | "fulfilled" | "cancelled"required
  • overduebooleanrequired

    Open and past due_on.

  • created_atstringrequired
  • fulfilled_atstring | nullrequired
  • fulfilled_document_idstring | nullrequired
  • cancelled_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"
}'
Response
{
  "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_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • person_idstring
  • status"open" | "fulfilled" | "cancelled" | "all"

    Default "open".

Returns

  • requestsobject[]required
    11 fields
    • idstringrequired
    • personobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • categorystringrequired
    • notestring | nullrequired
    • due_onstring | nullrequired
    • status"open" | "fulfilled" | "cancelled"required
    • overduebooleanrequired

      Open and past due_on.

    • created_atstringrequired
    • fulfilled_atstring | nullrequired
    • fulfilled_document_idstring | nullrequired
    • cancelled_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_cancel on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • request_idstringrequired

Returns

11 fields
  • idstringrequired
  • personobject | nullrequired
    2 fields
    • idstringrequired
    • namestringrequired
  • categorystringrequired
  • notestring | nullrequired
  • due_onstring | nullrequired
  • status"open" | "fulfilled" | "cancelled"required
  • overduebooleanrequired

    Open and past due_on.

  • created_atstringrequired
  • fulfilled_atstring | nullrequired
  • fulfilled_document_idstring | nullrequired
  • cancelled_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_list on HR Assistant
Method
POST with a JSON body, or GET with 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.

  • countrystring

    Pattern ^[A-Z]{2}$.

  • status"draft" | "published" | "archived" | "all"

    Default: drafts and published (not archived).

  • source"builtin" | "company"

Returns

  • templatesobject[]required
    20 fields
    • idstringrequired

      A company template's id, or a built-in's (builtin:…).

    • source"builtin" | "company"required

      builtin: Bizisy's (copy it to change it); company: your own.

    • kindstring (enum)required

      contract_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.

    • namestringrequired
    • categorystringrequired

      The Documents category the generated documents get.

    • countriesstring[]required

      The countries it is for (* = every country).

    • languages"en" | "pt" | "es" | "fr" | "de" | "it"[]required
    • signersobject[]required

      Who 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"required
      • person_idstringrequired
    • visibility"hr" | "hr_person" | "hr_person_manager"required

      Who sees the generated documents: hr, hr_person (default) or hr_person_manager.

    • status"draft" | "published" | "archived"required
    • versionintegerrequired

      The latest published version (0: never published).

    • has_draftbooleanrequired

      The draft has changes not published yet.

    • tier"public" | "job" | "private" | "pay"required

      The 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 | nullrequired

      Built-ins: a local employment lawyer reviewed the text (false: not yet). null for your own.

    • builtin_fromstring | nullrequired

      The template it was copied from.

    • updated_atstring | nullrequired
    • slotsobject[]required

      Clause slots ({{#clauses "name"}}): the clause types HR may pick there when generating, and the ones ticked by default.

      3 fields
      • namestringrequired
      • allowedstring (enum)[]required

        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.

      • defaultsstring (enum)[]required

        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.

    • letter_kind"permanent" | "fixed_term"required

      Offer letters: the contract kind Hiring uses it for (permanent; fixed_term, also temporary and internship contracts). null for other kinds.

    • approvalobject | nullrequired

      A version waiting for approval, or sent back with a comment (when your company requires approval to publish).

      7 fields
      • state"pending" | "rejected"required

        pending: waits for an approver; rejected: sent back (the draft is unchanged: change it and publish again).

      • approvers"hr" | "owner"required

        hr: an owner, admin or HR member; owner: an owner. Never whoever asked or changed the draft last.

      • versionintegerrequired

        The version it makes once approved.

      • asked_atstringrequired
      • asked_by_youbooleanrequired
      • can_decidebooleanrequired

        You may approve it or send it back (signed in to Bizisy, an approver by the rule, not its asker or last editor).

      • decidedobject | nullrequired

        When it was sent back, with the approver's comment.

        2 fields
        • atstringrequired
        • commentstring | nullrequired
    • style"international" | "continental"required

      The 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
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"
}'
Response
{
  "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_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • template_idstringrequired

Returns

26 fields
  • idstringrequired

    A company template's id, or a built-in's (builtin:…).

  • source"builtin" | "company"required

    builtin: Bizisy's (copy it to change it); company: your own.

  • kindstring (enum)required

    contract_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.

  • namestringrequired
  • categorystringrequired

    The Documents category the generated documents get.

  • countriesstring[]required

    The countries it is for (* = every country).

  • languages"en" | "pt" | "es" | "fr" | "de" | "it"[]required
  • signersobject[]required

    Who 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"required
    • person_idstringrequired
  • visibility"hr" | "hr_person" | "hr_person_manager"required

    Who sees the generated documents: hr, hr_person (default) or hr_person_manager.

  • status"draft" | "published" | "archived"required
  • versionintegerrequired

    The latest published version (0: never published).

  • has_draftbooleanrequired

    The draft has changes not published yet.

  • tier"public" | "job" | "private" | "pay"required

    The 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 | nullrequired

    Built-ins: a local employment lawyer reviewed the text (false: not yet). null for your own.

  • builtin_fromstring | nullrequired

    The template it was copied from.

  • updated_atstring | nullrequired
  • slotsobject[]required

    Clause slots ({{#clauses "name"}}): the clause types HR may pick there when generating, and the ones ticked by default.

    3 fields
    • namestringrequired
    • allowedstring (enum)[]required

      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.

    • defaultsstring (enum)[]required

      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.

  • letter_kind"permanent" | "fixed_term"required

    Offer letters: the contract kind Hiring uses it for (permanent; fixed_term, also temporary and internship contracts). null for other kinds.

  • approvalobject | nullrequired

    A version waiting for approval, or sent back with a comment (when your company requires approval to publish).

    7 fields
    • state"pending" | "rejected"required

      pending: waits for an approver; rejected: sent back (the draft is unchanged: change it and publish again).

    • approvers"hr" | "owner"required

      hr: an owner, admin or HR member; owner: an owner. Never whoever asked or changed the draft last.

    • versionintegerrequired

      The version it makes once approved.

    • asked_atstringrequired
    • asked_by_youbooleanrequired
    • can_decidebooleanrequired

      You may approve it or send it back (signed in to Bizisy, an approver by the rule, not its asker or last editor).

    • decidedobject | nullrequired

      When it was sent back, with the approver's comment.

      2 fields
      • atstringrequired
      • commentstring | nullrequired
  • style"international" | "continental"required

    The 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 | nullrequired

    Each language's title and body; null when the template uses pay details and you can't see pay.

    6 fields
    • enobject
      2 fields
      • titlestringrequired
      • bodystringrequired
    • ptobject
      2 fields
      • titlestringrequired
      • bodystringrequired
    • esobject
      2 fields
      • titlestringrequired
      • bodystringrequired
    • frobject
      2 fields
      • titlestringrequired
      • bodystringrequired
    • deobject
      2 fields
      • titlestringrequired
      • bodystringrequired
    • itobject
      2 fields
      • titlestringrequired
      • bodystringrequired
  • body_hiddenbooleanrequired
  • versionsobject[]required

    Published versions, newest first (built-ins: none listed).

    3 fields
    • versionintegerrequired
    • published_atstringrequired
    • tier"public" | "job" | "private" | "pay"required
  • problemsobject[]required

    Warnings in the draft (errors are refused when saving).

    8 fields
    • language"en" | "pt" | "es" | "fr" | "de" | "it"required
    • field"title" | "body"required
    • lineintegerrequired
    • colintegerrequired
    • codestringrequired
    • messagestringrequired

      English; the app translates by code.

    • severity"error" | "warning"required
    • paramsobject
  • fieldsstring[]required

    The fields the template uses.

  • lawobject[]required

    Per country it is for (EU: the Directive minimum when it is for every country).

    11 fields
    • countrystringrequired

      The country whose rules apply (EU: Directive 2019/1152, for any other country).

    • reviewedbooleanrequired

      A local employment lawyer checked this country's rules.

    • coveredobject[]required
      6 fields
      • idstringrequired
      • labelstringrequired

        English; the app translates it.

      • requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
      • notestring | nullrequired
    • missingobject[]required

      Required items the template does not cover.

      6 fields
      • idstringrequired
      • labelstringrequired

        English; the app translates it.

      • requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
      • notestring | nullrequired
    • optionalobject[]required

      Items needed only sometimes (fixed-term, probation…) that it does not cover.

      6 fields
      • idstringrequired
      • labelstringrequired

        English; the app translates it.

      • requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
      • notestring | nullrequired
    • manualobject[]required

      Items Bizisy cannot check by field: make sure the text says them.

      6 fields
      • idstringrequired
      • labelstringrequired

        English; the app translates it.

      • requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
      • notestring | nullrequired
    • signatureobjectrequired
      6 fields
      • min_level"none" | "simple" | "advanced" | "qualified" | "wet"required

        The lowest signature level that makes it valid (wet: printed and signed by hand).

      • whostring[]required
      • notestringrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required

        Only verified rules block; others warn.

      • alternativesstring[]required
    • deliveryobjectrequired
      3 fields
      • deadlinestringrequired

        before_start, on_start, days_after_start, by_effective_date, before_end, on_last_day, on_request or none.

      • proof_requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
    • languageobjectrequired
      3 fields
      • mandatorystring | nullrequired
      • defaultstring | nullrequired
      • translation_allowedbooleanrequired
    • dueobject[]required

      For a person: by when each part must reach them.

      2 fields
      • partstringrequired
      • duestringrequired
    • disclaimerstringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/documents/templates.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template_id":"tpl1"}'
Response
{
  "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_create on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • kindstring (enum)required

    One of: contract_open, contract_fixed, contract_part_time, statement, amendment, change_notice, end_notice, certificate, declaration, policy, letter, offer_letter, pay_review_letter.

  • namestringrequired

    1–120 characters.

  • categorystringrequired

    1–40 characters.

  • countriesstring[]

    Default ["*"]: every country.

    1–30 items. Pattern ^([A-Z]{2}|\*)$.

  • bodiesobjectrequired
    6 fields
    • enobject
      2 fields
      • titlestringrequired

        The generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".

        1–200 characters.

      • bodystringrequired

        The 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.

    • ptobject
      2 fields
      • titlestringrequired

        The generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".

        1–200 characters.

      • bodystringrequired

        The 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.

    • esobject
      2 fields
      • titlestringrequired

        The generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".

        1–200 characters.

      • bodystringrequired

        The 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.

    • frobject
      2 fields
      • titlestringrequired

        The generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".

        1–200 characters.

      • bodystringrequired

        The 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.

    • deobject
      2 fields
      • titlestringrequired

        The generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".

        1–200 characters.

      • bodystringrequired

        The 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.

    • itobject
      2 fields
      • titlestringrequired

        The generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".

        1–200 characters.

      • bodystringrequired

        The 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"required
    • person_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
    • namestringrequired

      1–40 characters. Pattern ^[a-z][a-z0-9_]*$.

    • allowedstring (enum)[]required

      The 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)[]required

      Ticked 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
  • idstringrequired

    A company template's id, or a built-in's (builtin:…).

  • source"builtin" | "company"required

    builtin: Bizisy's (copy it to change it); company: your own.

  • kindstring (enum)required

    contract_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.

  • namestringrequired
  • categorystringrequired

    The Documents category the generated documents get.

  • countriesstring[]required

    The countries it is for (* = every country).

  • languages"en" | "pt" | "es" | "fr" | "de" | "it"[]required
  • signersobject[]required

    Who 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"required
    • person_idstringrequired
  • visibility"hr" | "hr_person" | "hr_person_manager"required

    Who sees the generated documents: hr, hr_person (default) or hr_person_manager.

  • status"draft" | "published" | "archived"required
  • versionintegerrequired

    The latest published version (0: never published).

  • has_draftbooleanrequired

    The draft has changes not published yet.

  • tier"public" | "job" | "private" | "pay"required

    The 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 | nullrequired

    Built-ins: a local employment lawyer reviewed the text (false: not yet). null for your own.

  • builtin_fromstring | nullrequired

    The template it was copied from.

  • updated_atstring | nullrequired
  • slotsobject[]required

    Clause slots ({{#clauses "name"}}): the clause types HR may pick there when generating, and the ones ticked by default.

    3 fields
    • namestringrequired
    • allowedstring (enum)[]required

      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.

    • defaultsstring (enum)[]required

      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.

  • letter_kind"permanent" | "fixed_term"required

    Offer letters: the contract kind Hiring uses it for (permanent; fixed_term, also temporary and internship contracts). null for other kinds.

  • approvalobject | nullrequired

    A version waiting for approval, or sent back with a comment (when your company requires approval to publish).

    7 fields
    • state"pending" | "rejected"required

      pending: waits for an approver; rejected: sent back (the draft is unchanged: change it and publish again).

    • approvers"hr" | "owner"required

      hr: an owner, admin or HR member; owner: an owner. Never whoever asked or changed the draft last.

    • versionintegerrequired

      The version it makes once approved.

    • asked_atstringrequired
    • asked_by_youbooleanrequired
    • can_decidebooleanrequired

      You may approve it or send it back (signed in to Bizisy, an approver by the rule, not its asker or last editor).

    • decidedobject | nullrequired

      When it was sent back, with the approver's comment.

      2 fields
      • atstringrequired
      • commentstring | nullrequired
  • style"international" | "continental"required

    The 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 | nullrequired

    Each language's title and body; null when the template uses pay details and you can't see pay.

    6 fields
    • enobject
      2 fields
      • titlestringrequired
      • bodystringrequired
    • ptobject
      2 fields
      • titlestringrequired
      • bodystringrequired
    • esobject
      2 fields
      • titlestringrequired
      • bodystringrequired
    • frobject
      2 fields
      • titlestringrequired
      • bodystringrequired
    • deobject
      2 fields
      • titlestringrequired
      • bodystringrequired
    • itobject
      2 fields
      • titlestringrequired
      • bodystringrequired
  • body_hiddenbooleanrequired
  • versionsobject[]required

    Published versions, newest first (built-ins: none listed).

    3 fields
    • versionintegerrequired
    • published_atstringrequired
    • tier"public" | "job" | "private" | "pay"required
  • problemsobject[]required

    Warnings in the draft (errors are refused when saving).

    8 fields
    • language"en" | "pt" | "es" | "fr" | "de" | "it"required
    • field"title" | "body"required
    • lineintegerrequired
    • colintegerrequired
    • codestringrequired
    • messagestringrequired

      English; the app translates by code.

    • severity"error" | "warning"required
    • paramsobject
  • fieldsstring[]required

    The fields the template uses.

  • lawobject[]required

    Per country it is for (EU: the Directive minimum when it is for every country).

    11 fields
    • countrystringrequired

      The country whose rules apply (EU: Directive 2019/1152, for any other country).

    • reviewedbooleanrequired

      A local employment lawyer checked this country's rules.

    • coveredobject[]required
      6 fields
      • idstringrequired
      • labelstringrequired

        English; the app translates it.

      • requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
      • notestring | nullrequired
    • missingobject[]required

      Required items the template does not cover.

      6 fields
      • idstringrequired
      • labelstringrequired

        English; the app translates it.

      • requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
      • notestring | nullrequired
    • optionalobject[]required

      Items needed only sometimes (fixed-term, probation…) that it does not cover.

      6 fields
      • idstringrequired
      • labelstringrequired

        English; the app translates it.

      • requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
      • notestring | nullrequired
    • manualobject[]required

      Items Bizisy cannot check by field: make sure the text says them.

      6 fields
      • idstringrequired
      • labelstringrequired

        English; the app translates it.

      • requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
      • notestring | nullrequired
    • signatureobjectrequired
      6 fields
      • min_level"none" | "simple" | "advanced" | "qualified" | "wet"required

        The lowest signature level that makes it valid (wet: printed and signed by hand).

      • whostring[]required
      • notestringrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required

        Only verified rules block; others warn.

      • alternativesstring[]required
    • deliveryobjectrequired
      3 fields
      • deadlinestringrequired

        before_start, on_start, days_after_start, by_effective_date, before_end, on_last_day, on_request or none.

      • proof_requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
    • languageobjectrequired
      3 fields
      • mandatorystring | nullrequired
      • defaultstring | nullrequired
      • translation_allowedbooleanrequired
    • dueobject[]required

      For a person: by when each part must reach them.

      2 fields
      • partstringrequired
      • duestringrequired
    • disclaimerstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"
}'
Response
{
  "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_update on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • template_idstringrequired
  • namestring

    1–120 characters.

  • categorystring

    1–40 characters.

  • countriesstring[]

    1–30 items. Pattern ^([A-Z]{2}|\*)$.

  • bodiesobject
    6 fields
    • enobject
      2 fields
      • titlestringrequired

        The generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".

        1–200 characters.

      • bodystringrequired

        The 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.

    • ptobject
      2 fields
      • titlestringrequired

        The generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".

        1–200 characters.

      • bodystringrequired

        The 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.

    • esobject
      2 fields
      • titlestringrequired

        The generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".

        1–200 characters.

      • bodystringrequired

        The 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.

    • frobject
      2 fields
      • titlestringrequired

        The generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".

        1–200 characters.

      • bodystringrequired

        The 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.

    • deobject
      2 fields
      • titlestringrequired

        The generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".

        1–200 characters.

      • bodystringrequired

        The 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.

    • itobject
      2 fields
      • titlestringrequired

        The generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".

        1–200 characters.

      • bodystringrequired

        The 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"required
    • person_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
    • namestringrequired

      1–40 characters. Pattern ^[a-z][a-z0-9_]*$.

    • allowedstring (enum)[]required

      The 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)[]required

      Ticked 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
  • idstringrequired

    A company template's id, or a built-in's (builtin:…).

  • source"builtin" | "company"required

    builtin: Bizisy's (copy it to change it); company: your own.

  • kindstring (enum)required

    contract_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.

  • namestringrequired
  • categorystringrequired

    The Documents category the generated documents get.

  • countriesstring[]required

    The countries it is for (* = every country).

  • languages"en" | "pt" | "es" | "fr" | "de" | "it"[]required
  • signersobject[]required

    Who 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"required
    • person_idstringrequired
  • visibility"hr" | "hr_person" | "hr_person_manager"required

    Who sees the generated documents: hr, hr_person (default) or hr_person_manager.

  • status"draft" | "published" | "archived"required
  • versionintegerrequired

    The latest published version (0: never published).

  • has_draftbooleanrequired

    The draft has changes not published yet.

  • tier"public" | "job" | "private" | "pay"required

    The 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 | nullrequired

    Built-ins: a local employment lawyer reviewed the text (false: not yet). null for your own.

  • builtin_fromstring | nullrequired

    The template it was copied from.

  • updated_atstring | nullrequired
  • slotsobject[]required

    Clause slots ({{#clauses "name"}}): the clause types HR may pick there when generating, and the ones ticked by default.

    3 fields
    • namestringrequired
    • allowedstring (enum)[]required

      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.

    • defaultsstring (enum)[]required

      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.

  • letter_kind"permanent" | "fixed_term"required

    Offer letters: the contract kind Hiring uses it for (permanent; fixed_term, also temporary and internship contracts). null for other kinds.

  • approvalobject | nullrequired

    A version waiting for approval, or sent back with a comment (when your company requires approval to publish).

    7 fields
    • state"pending" | "rejected"required

      pending: waits for an approver; rejected: sent back (the draft is unchanged: change it and publish again).

    • approvers"hr" | "owner"required

      hr: an owner, admin or HR member; owner: an owner. Never whoever asked or changed the draft last.

    • versionintegerrequired

      The version it makes once approved.

    • asked_atstringrequired
    • asked_by_youbooleanrequired
    • can_decidebooleanrequired

      You may approve it or send it back (signed in to Bizisy, an approver by the rule, not its asker or last editor).

    • decidedobject | nullrequired

      When it was sent back, with the approver's comment.

      2 fields
      • atstringrequired
      • commentstring | nullrequired
  • style"international" | "continental"required

    The 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 | nullrequired

    Each language's title and body; null when the template uses pay details and you can't see pay.

    6 fields
    • enobject
      2 fields
      • titlestringrequired
      • bodystringrequired
    • ptobject
      2 fields
      • titlestringrequired
      • bodystringrequired
    • esobject
      2 fields
      • titlestringrequired
      • bodystringrequired
    • frobject
      2 fields
      • titlestringrequired
      • bodystringrequired
    • deobject
      2 fields
      • titlestringrequired
      • bodystringrequired
    • itobject
      2 fields
      • titlestringrequired
      • bodystringrequired
  • body_hiddenbooleanrequired
  • versionsobject[]required

    Published versions, newest first (built-ins: none listed).

    3 fields
    • versionintegerrequired
    • published_atstringrequired
    • tier"public" | "job" | "private" | "pay"required
  • problemsobject[]required

    Warnings in the draft (errors are refused when saving).

    8 fields
    • language"en" | "pt" | "es" | "fr" | "de" | "it"required
    • field"title" | "body"required
    • lineintegerrequired
    • colintegerrequired
    • codestringrequired
    • messagestringrequired

      English; the app translates by code.

    • severity"error" | "warning"required
    • paramsobject
  • fieldsstring[]required

    The fields the template uses.

  • lawobject[]required

    Per country it is for (EU: the Directive minimum when it is for every country).

    11 fields
    • countrystringrequired

      The country whose rules apply (EU: Directive 2019/1152, for any other country).

    • reviewedbooleanrequired

      A local employment lawyer checked this country's rules.

    • coveredobject[]required
      6 fields
      • idstringrequired
      • labelstringrequired

        English; the app translates it.

      • requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
      • notestring | nullrequired
    • missingobject[]required

      Required items the template does not cover.

      6 fields
      • idstringrequired
      • labelstringrequired

        English; the app translates it.

      • requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
      • notestring | nullrequired
    • optionalobject[]required

      Items needed only sometimes (fixed-term, probation…) that it does not cover.

      6 fields
      • idstringrequired
      • labelstringrequired

        English; the app translates it.

      • requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
      • notestring | nullrequired
    • manualobject[]required

      Items Bizisy cannot check by field: make sure the text says them.

      6 fields
      • idstringrequired
      • labelstringrequired

        English; the app translates it.

      • requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
      • notestring | nullrequired
    • signatureobjectrequired
      6 fields
      • min_level"none" | "simple" | "advanced" | "qualified" | "wet"required

        The lowest signature level that makes it valid (wet: printed and signed by hand).

      • whostring[]required
      • notestringrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required

        Only verified rules block; others warn.

      • alternativesstring[]required
    • deliveryobjectrequired
      3 fields
      • deadlinestringrequired

        before_start, on_start, days_after_start, by_effective_date, before_end, on_last_day, on_request or none.

      • proof_requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
    • languageobjectrequired
      3 fields
      • mandatorystring | nullrequired
      • defaultstring | nullrequired
      • translation_allowedbooleanrequired
    • dueobject[]required

      For a person: by when each part must reach them.

      2 fields
      • partstringrequired
      • duestringrequired
    • disclaimerstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"
}'
Response
{
  "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_copy on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • template_idstringrequired
  • namestring

    1–120 characters.

Returns

26 fields
  • idstringrequired

    A company template's id, or a built-in's (builtin:…).

  • source"builtin" | "company"required

    builtin: Bizisy's (copy it to change it); company: your own.

  • kindstring (enum)required

    contract_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.

  • namestringrequired
  • categorystringrequired

    The Documents category the generated documents get.

  • countriesstring[]required

    The countries it is for (* = every country).

  • languages"en" | "pt" | "es" | "fr" | "de" | "it"[]required
  • signersobject[]required

    Who 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"required
    • person_idstringrequired
  • visibility"hr" | "hr_person" | "hr_person_manager"required

    Who sees the generated documents: hr, hr_person (default) or hr_person_manager.

  • status"draft" | "published" | "archived"required
  • versionintegerrequired

    The latest published version (0: never published).

  • has_draftbooleanrequired

    The draft has changes not published yet.

  • tier"public" | "job" | "private" | "pay"required

    The 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 | nullrequired

    Built-ins: a local employment lawyer reviewed the text (false: not yet). null for your own.

  • builtin_fromstring | nullrequired

    The template it was copied from.

  • updated_atstring | nullrequired
  • slotsobject[]required

    Clause slots ({{#clauses "name"}}): the clause types HR may pick there when generating, and the ones ticked by default.

    3 fields
    • namestringrequired
    • allowedstring (enum)[]required

      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.

    • defaultsstring (enum)[]required

      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.

  • letter_kind"permanent" | "fixed_term"required

    Offer letters: the contract kind Hiring uses it for (permanent; fixed_term, also temporary and internship contracts). null for other kinds.

  • approvalobject | nullrequired

    A version waiting for approval, or sent back with a comment (when your company requires approval to publish).

    7 fields
    • state"pending" | "rejected"required

      pending: waits for an approver; rejected: sent back (the draft is unchanged: change it and publish again).

    • approvers"hr" | "owner"required

      hr: an owner, admin or HR member; owner: an owner. Never whoever asked or changed the draft last.

    • versionintegerrequired

      The version it makes once approved.

    • asked_atstringrequired
    • asked_by_youbooleanrequired
    • can_decidebooleanrequired

      You may approve it or send it back (signed in to Bizisy, an approver by the rule, not its asker or last editor).

    • decidedobject | nullrequired

      When it was sent back, with the approver's comment.

      2 fields
      • atstringrequired
      • commentstring | nullrequired
  • style"international" | "continental"required

    The 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 | nullrequired

    Each language's title and body; null when the template uses pay details and you can't see pay.

    6 fields
    • enobject
      2 fields
      • titlestringrequired
      • bodystringrequired
    • ptobject
      2 fields
      • titlestringrequired
      • bodystringrequired
    • esobject
      2 fields
      • titlestringrequired
      • bodystringrequired
    • frobject
      2 fields
      • titlestringrequired
      • bodystringrequired
    • deobject
      2 fields
      • titlestringrequired
      • bodystringrequired
    • itobject
      2 fields
      • titlestringrequired
      • bodystringrequired
  • body_hiddenbooleanrequired
  • versionsobject[]required

    Published versions, newest first (built-ins: none listed).

    3 fields
    • versionintegerrequired
    • published_atstringrequired
    • tier"public" | "job" | "private" | "pay"required
  • problemsobject[]required

    Warnings in the draft (errors are refused when saving).

    8 fields
    • language"en" | "pt" | "es" | "fr" | "de" | "it"required
    • field"title" | "body"required
    • lineintegerrequired
    • colintegerrequired
    • codestringrequired
    • messagestringrequired

      English; the app translates by code.

    • severity"error" | "warning"required
    • paramsobject
  • fieldsstring[]required

    The fields the template uses.

  • lawobject[]required

    Per country it is for (EU: the Directive minimum when it is for every country).

    11 fields
    • countrystringrequired

      The country whose rules apply (EU: Directive 2019/1152, for any other country).

    • reviewedbooleanrequired

      A local employment lawyer checked this country's rules.

    • coveredobject[]required
      6 fields
      • idstringrequired
      • labelstringrequired

        English; the app translates it.

      • requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
      • notestring | nullrequired
    • missingobject[]required

      Required items the template does not cover.

      6 fields
      • idstringrequired
      • labelstringrequired

        English; the app translates it.

      • requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
      • notestring | nullrequired
    • optionalobject[]required

      Items needed only sometimes (fixed-term, probation…) that it does not cover.

      6 fields
      • idstringrequired
      • labelstringrequired

        English; the app translates it.

      • requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
      • notestring | nullrequired
    • manualobject[]required

      Items Bizisy cannot check by field: make sure the text says them.

      6 fields
      • idstringrequired
      • labelstringrequired

        English; the app translates it.

      • requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
      • notestring | nullrequired
    • signatureobjectrequired
      6 fields
      • min_level"none" | "simple" | "advanced" | "qualified" | "wet"required

        The lowest signature level that makes it valid (wet: printed and signed by hand).

      • whostring[]required
      • notestringrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required

        Only verified rules block; others warn.

      • alternativesstring[]required
    • deliveryobjectrequired
      3 fields
      • deadlinestringrequired

        before_start, on_start, days_after_start, by_effective_date, before_end, on_last_day, on_request or none.

      • proof_requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
    • languageobjectrequired
      3 fields
      • mandatorystring | nullrequired
      • defaultstring | nullrequired
      • translation_allowedbooleanrequired
    • dueobject[]required

      For a person: by when each part must reach them.

      2 fields
      • partstringrequired
      • duestringrequired
    • disclaimerstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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)"}'
Response
{
  "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_archive on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • template_idstringrequired
  • archivedboolean

    Default true; false restores it.

Returns

26 fields
  • idstringrequired

    A company template's id, or a built-in's (builtin:…).

  • source"builtin" | "company"required

    builtin: Bizisy's (copy it to change it); company: your own.

  • kindstring (enum)required

    contract_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.

  • namestringrequired
  • categorystringrequired

    The Documents category the generated documents get.

  • countriesstring[]required

    The countries it is for (* = every country).

  • languages"en" | "pt" | "es" | "fr" | "de" | "it"[]required
  • signersobject[]required

    Who 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"required
    • person_idstringrequired
  • visibility"hr" | "hr_person" | "hr_person_manager"required

    Who sees the generated documents: hr, hr_person (default) or hr_person_manager.

  • status"draft" | "published" | "archived"required
  • versionintegerrequired

    The latest published version (0: never published).

  • has_draftbooleanrequired

    The draft has changes not published yet.

  • tier"public" | "job" | "private" | "pay"required

    The 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 | nullrequired

    Built-ins: a local employment lawyer reviewed the text (false: not yet). null for your own.

  • builtin_fromstring | nullrequired

    The template it was copied from.

  • updated_atstring | nullrequired
  • slotsobject[]required

    Clause slots ({{#clauses "name"}}): the clause types HR may pick there when generating, and the ones ticked by default.

    3 fields
    • namestringrequired
    • allowedstring (enum)[]required

      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.

    • defaultsstring (enum)[]required

      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.

  • letter_kind"permanent" | "fixed_term"required

    Offer letters: the contract kind Hiring uses it for (permanent; fixed_term, also temporary and internship contracts). null for other kinds.

  • approvalobject | nullrequired

    A version waiting for approval, or sent back with a comment (when your company requires approval to publish).

    7 fields
    • state"pending" | "rejected"required

      pending: waits for an approver; rejected: sent back (the draft is unchanged: change it and publish again).

    • approvers"hr" | "owner"required

      hr: an owner, admin or HR member; owner: an owner. Never whoever asked or changed the draft last.

    • versionintegerrequired

      The version it makes once approved.

    • asked_atstringrequired
    • asked_by_youbooleanrequired
    • can_decidebooleanrequired

      You may approve it or send it back (signed in to Bizisy, an approver by the rule, not its asker or last editor).

    • decidedobject | nullrequired

      When it was sent back, with the approver's comment.

      2 fields
      • atstringrequired
      • commentstring | nullrequired
  • style"international" | "continental"required

    The 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 | nullrequired

    Each language's title and body; null when the template uses pay details and you can't see pay.

    6 fields
    • enobject
      2 fields
      • titlestringrequired
      • bodystringrequired
    • ptobject
      2 fields
      • titlestringrequired
      • bodystringrequired
    • esobject
      2 fields
      • titlestringrequired
      • bodystringrequired
    • frobject
      2 fields
      • titlestringrequired
      • bodystringrequired
    • deobject
      2 fields
      • titlestringrequired
      • bodystringrequired
    • itobject
      2 fields
      • titlestringrequired
      • bodystringrequired
  • body_hiddenbooleanrequired
  • versionsobject[]required

    Published versions, newest first (built-ins: none listed).

    3 fields
    • versionintegerrequired
    • published_atstringrequired
    • tier"public" | "job" | "private" | "pay"required
  • problemsobject[]required

    Warnings in the draft (errors are refused when saving).

    8 fields
    • language"en" | "pt" | "es" | "fr" | "de" | "it"required
    • field"title" | "body"required
    • lineintegerrequired
    • colintegerrequired
    • codestringrequired
    • messagestringrequired

      English; the app translates by code.

    • severity"error" | "warning"required
    • paramsobject
  • fieldsstring[]required

    The fields the template uses.

  • lawobject[]required

    Per country it is for (EU: the Directive minimum when it is for every country).

    11 fields
    • countrystringrequired

      The country whose rules apply (EU: Directive 2019/1152, for any other country).

    • reviewedbooleanrequired

      A local employment lawyer checked this country's rules.

    • coveredobject[]required
      6 fields
      • idstringrequired
      • labelstringrequired

        English; the app translates it.

      • requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
      • notestring | nullrequired
    • missingobject[]required

      Required items the template does not cover.

      6 fields
      • idstringrequired
      • labelstringrequired

        English; the app translates it.

      • requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
      • notestring | nullrequired
    • optionalobject[]required

      Items needed only sometimes (fixed-term, probation…) that it does not cover.

      6 fields
      • idstringrequired
      • labelstringrequired

        English; the app translates it.

      • requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
      • notestring | nullrequired
    • manualobject[]required

      Items Bizisy cannot check by field: make sure the text says them.

      6 fields
      • idstringrequired
      • labelstringrequired

        English; the app translates it.

      • requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
      • notestring | nullrequired
    • signatureobjectrequired
      6 fields
      • min_level"none" | "simple" | "advanced" | "qualified" | "wet"required

        The lowest signature level that makes it valid (wet: printed and signed by hand).

      • whostring[]required
      • notestringrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required

        Only verified rules block; others warn.

      • alternativesstring[]required
    • deliveryobjectrequired
      3 fields
      • deadlinestringrequired

        before_start, on_start, days_after_start, by_effective_date, before_end, on_last_day, on_request or none.

      • proof_requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
    • languageobjectrequired
      3 fields
      • mandatorystring | nullrequired
      • defaultstring | nullrequired
      • translation_allowedbooleanrequired
    • dueobject[]required

      For a person: by when each part must reach them.

      2 fields
      • partstringrequired
      • duestringrequired
    • disclaimerstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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}'
Response
{
  "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_publish on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • template_idstringrequired

Returns

28 fields
  • idstringrequired

    A company template's id, or a built-in's (builtin:…).

  • source"builtin" | "company"required

    builtin: Bizisy's (copy it to change it); company: your own.

  • kindstring (enum)required

    contract_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.

  • namestringrequired
  • categorystringrequired

    The Documents category the generated documents get.

  • countriesstring[]required

    The countries it is for (* = every country).

  • languages"en" | "pt" | "es" | "fr" | "de" | "it"[]required
  • signersobject[]required

    Who 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"required
    • person_idstringrequired
  • visibility"hr" | "hr_person" | "hr_person_manager"required

    Who sees the generated documents: hr, hr_person (default) or hr_person_manager.

  • status"draft" | "published" | "archived"required
  • versionintegerrequired

    The latest published version (0: never published).

  • has_draftbooleanrequired

    The draft has changes not published yet.

  • tier"public" | "job" | "private" | "pay"required

    The 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 | nullrequired

    Built-ins: a local employment lawyer reviewed the text (false: not yet). null for your own.

  • builtin_fromstring | nullrequired

    The template it was copied from.

  • updated_atstring | nullrequired
  • slotsobject[]required

    Clause slots ({{#clauses "name"}}): the clause types HR may pick there when generating, and the ones ticked by default.

    3 fields
    • namestringrequired
    • allowedstring (enum)[]required

      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.

    • defaultsstring (enum)[]required

      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.

  • letter_kind"permanent" | "fixed_term"required

    Offer letters: the contract kind Hiring uses it for (permanent; fixed_term, also temporary and internship contracts). null for other kinds.

  • approvalobject | nullrequired

    A version waiting for approval, or sent back with a comment (when your company requires approval to publish).

    7 fields
    • state"pending" | "rejected"required

      pending: waits for an approver; rejected: sent back (the draft is unchanged: change it and publish again).

    • approvers"hr" | "owner"required

      hr: an owner, admin or HR member; owner: an owner. Never whoever asked or changed the draft last.

    • versionintegerrequired

      The version it makes once approved.

    • asked_atstringrequired
    • asked_by_youbooleanrequired
    • can_decidebooleanrequired

      You may approve it or send it back (signed in to Bizisy, an approver by the rule, not its asker or last editor).

    • decidedobject | nullrequired

      When it was sent back, with the approver's comment.

      2 fields
      • atstringrequired
      • commentstring | nullrequired
  • style"international" | "continental"required

    The 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 | nullrequired

    Each language's title and body; null when the template uses pay details and you can't see pay.

    6 fields
    • enobject
      2 fields
      • titlestringrequired
      • bodystringrequired
    • ptobject
      2 fields
      • titlestringrequired
      • bodystringrequired
    • esobject
      2 fields
      • titlestringrequired
      • bodystringrequired
    • frobject
      2 fields
      • titlestringrequired
      • bodystringrequired
    • deobject
      2 fields
      • titlestringrequired
      • bodystringrequired
    • itobject
      2 fields
      • titlestringrequired
      • bodystringrequired
  • body_hiddenbooleanrequired
  • versionsobject[]required

    Published versions, newest first (built-ins: none listed).

    3 fields
    • versionintegerrequired
    • published_atstringrequired
    • tier"public" | "job" | "private" | "pay"required
  • problemsobject[]required

    Warnings in the draft (errors are refused when saving).

    8 fields
    • language"en" | "pt" | "es" | "fr" | "de" | "it"required
    • field"title" | "body"required
    • lineintegerrequired
    • colintegerrequired
    • codestringrequired
    • messagestringrequired

      English; the app translates by code.

    • severity"error" | "warning"required
    • paramsobject
  • fieldsstring[]required

    The fields the template uses.

  • lawobject[]required

    Per country it is for (EU: the Directive minimum when it is for every country).

    11 fields
    • countrystringrequired

      The country whose rules apply (EU: Directive 2019/1152, for any other country).

    • reviewedbooleanrequired

      A local employment lawyer checked this country's rules.

    • coveredobject[]required
      6 fields
      • idstringrequired
      • labelstringrequired

        English; the app translates it.

      • requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
      • notestring | nullrequired
    • missingobject[]required

      Required items the template does not cover.

      6 fields
      • idstringrequired
      • labelstringrequired

        English; the app translates it.

      • requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
      • notestring | nullrequired
    • optionalobject[]required

      Items needed only sometimes (fixed-term, probation…) that it does not cover.

      6 fields
      • idstringrequired
      • labelstringrequired

        English; the app translates it.

      • requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
      • notestring | nullrequired
    • manualobject[]required

      Items Bizisy cannot check by field: make sure the text says them.

      6 fields
      • idstringrequired
      • labelstringrequired

        English; the app translates it.

      • requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
      • notestring | nullrequired
    • signatureobjectrequired
      6 fields
      • min_level"none" | "simple" | "advanced" | "qualified" | "wet"required

        The lowest signature level that makes it valid (wet: printed and signed by hand).

      • whostring[]required
      • notestringrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required

        Only verified rules block; others warn.

      • alternativesstring[]required
    • deliveryobjectrequired
      3 fields
      • deadlinestringrequired

        before_start, on_start, days_after_start, by_effective_date, before_end, on_last_day, on_request or none.

      • proof_requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
    • languageobjectrequired
      3 fields
      • mandatorystring | nullrequired
      • defaultstring | nullrequired
      • translation_allowedbooleanrequired
    • dueobject[]required

      For a person: by when each part must reach them.

      2 fields
      • partstringrequired
      • duestringrequired
    • disclaimerstringrequired
  • published_versioninteger | nullrequired

    The version published; null when it waits for approval.

  • pending_approvalbooleanrequired

    It waits for an approver (your company requires approval to publish).

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_preview on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • template_idstring
  • versioninteger

    A published version (default: the draft; built-ins: their text).

    At least 1.

  • bodystring

    Up to 60000 characters.

  • titlestring

    Up 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_idstring
  • overridesobject

    Values for this document only, by field path (e.g. {"job.reason_for_term": "A seasonal peak"}).

  • clausesobject

    The clauses to put in (as documents_generate takes them, for this person): each slot's picks in order, and fixed clauses' fields. Default: each slot's defaults.

    2 fields
    • slotsobject

      Per clause slot, the clauses in order (an empty list: none). A slot left out gets its defaults.

    • fixedobject

      Fixed clauses ({{clause "type"}}): their typed fields, or another clause of that type.

      16 fields
      • non_competeobjectrequired
        2 fields
        • clause_idstring

          1–100 characters.

        • fieldsobject
      • non_solicitationobjectrequired
        2 fields
        • clause_idstring

          1–100 characters.

        • fieldsobject
      • probationobjectrequired
        2 fields
        • clause_idstring

          1–100 characters.

        • fieldsobject
      • training_repaymentobjectrequired
        2 fields
        • clause_idstring

          1–100 characters.

        • fieldsobject
      • remote_workobjectrequired
        2 fields
        • clause_idstring

          1–100 characters.

        • fieldsobject
      • exclusivityobjectrequired
        2 fields
        • clause_idstring

          1–100 characters.

        • fieldsobject
      • confidentialityobjectrequired
        2 fields
        • clause_idstring

          1–100 characters.

        • fieldsobject
      • ip_inventionsobjectrequired
        2 fields
        • clause_idstring

          1–100 characters.

        • fieldsobject
      • mobilityobjectrequired
        2 fields
        • clause_idstring

          1–100 characters.

        • fieldsobject
      • overtime_includedobjectrequired
        2 fields
        • clause_idstring

          1–100 characters.

        • fieldsobject
      • noticeobjectrequired
        2 fields
        • clause_idstring

          1–100 characters.

        • fieldsobject
      • garden_leaveobjectrequired
        2 fields
        • clause_idstring

          1–100 characters.

        • fieldsobject
      • equipmentobjectrequired
        2 fields
        • clause_idstring

          1–100 characters.

        • fieldsobject
      • monitoring_noticeobjectrequired
        2 fields
        • clause_idstring

          1–100 characters.

        • fieldsobject
      • collective_agreementobjectrequired
        2 fields
        • clause_idstring

          1–100 characters.

        • fieldsobject
      • pay_extra_monthsobjectrequired
        2 fields
        • clause_idstring

          1–100 characters.

        • fieldsobject
  • slotsobject[]

    With body: the slot settings being edited.

    Up to 10 items.

    3 fields
    • namestringrequired

      1–40 characters. Pattern ^[a-z][a-z0-9_]*$.

    • allowedstring (enum)[]required

      The 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)[]required

      Ticked 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
  • htmlstringrequired
  • titlestringrequired
  • language"en" | "pt" | "es" | "fr" | "de" | "it"required
  • samplebooleanrequired

    Filled for Bizisy's sample person.

  • tier"public" | "job" | "private" | "pay"required
  • problemsobject[]required
    8 fields
    • language"en" | "pt" | "es" | "fr" | "de" | "it"required
    • field"title" | "body"required
    • lineintegerrequired
    • colintegerrequired
    • codestringrequired
    • messagestringrequired

      English; the app translates by code.

    • severity"error" | "warning"required
    • paramsobject
  • missingstring[]required
  • droppedstring[]required
  • withheldstring[]required
  • lawobjectrequired
    11 fields
    • countrystringrequired

      The country whose rules apply (EU: Directive 2019/1152, for any other country).

    • reviewedbooleanrequired

      A local employment lawyer checked this country's rules.

    • coveredobject[]required
      6 fields
      • idstringrequired
      • labelstringrequired

        English; the app translates it.

      • requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
      • notestring | nullrequired
    • missingobject[]required

      Required items the template does not cover.

      6 fields
      • idstringrequired
      • labelstringrequired

        English; the app translates it.

      • requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
      • notestring | nullrequired
    • optionalobject[]required

      Items needed only sometimes (fixed-term, probation…) that it does not cover.

      6 fields
      • idstringrequired
      • labelstringrequired

        English; the app translates it.

      • requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
      • notestring | nullrequired
    • manualobject[]required

      Items Bizisy cannot check by field: make sure the text says them.

      6 fields
      • idstringrequired
      • labelstringrequired

        English; the app translates it.

      • requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
      • notestring | nullrequired
    • signatureobjectrequired
      6 fields
      • min_level"none" | "simple" | "advanced" | "qualified" | "wet"required

        The lowest signature level that makes it valid (wet: printed and signed by hand).

      • whostring[]required
      • notestringrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required

        Only verified rules block; others warn.

      • alternativesstring[]required
    • deliveryobjectrequired
      3 fields
      • deadlinestringrequired

        before_start, on_start, days_after_start, by_effective_date, before_end, on_last_day, on_request or none.

      • proof_requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
    • languageobjectrequired
      3 fields
      • mandatorystring | nullrequired
      • defaultstring | nullrequired
      • translation_allowedbooleanrequired
    • dueobject[]required

      For a person: by when each part must reach them.

      2 fields
      • partstringrequired
      • duestringrequired
    • disclaimerstringrequired
  • clausesobject[]required

    The clauses in it for this person: the variant of their country, the rules' result (blocks refuse generating), the law note.

    18 fields
    • okbooleanrequired

      No block: the clause may go in the document.

    • countrystring (enum)required

      Whose 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[]required

      The law Bizisy treats as settled is broken: the document is refused with it.

      6 fields
      • rulestringrequired
      • messagestringrequired

        English with {params}; the app translates it.

      • paramsobject | nullrequired
      • fieldstring | nullrequired

        The typed field it is about.

      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
    • warnsobject[]required

      Less certain rules and reminders: the document is made, check with your lawyer.

      6 fields
      • rulestringrequired
      • messagestringrequired

        English with {params}; the app translates it.

      • paramsobject | nullrequired
      • fieldstring | nullrequired

        The typed field it is about.

      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
    • raises_toobject | nullrequired

      The signature level the clause needs (e.g. a German non-compete: qualified or by hand).

      3 fields
      • level"none" | "simple" | "advanced" | "qualified" | "wet"required
      • confidence"verified" | "medium" | "uncertain"required
      • sourceobject | nullrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
    • tasksobject[]required

      To do once signed (Italy: file the smart-working agreement within 5 days).

      4 fields
      • idstringrequired
      • labelstringrequired
      • days_after_startintegerrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
    • fieldsobjectrequired

      The fields as checked (defaults filled in).

    • slotstring | nullrequired

      The slot it is in (null: a fixed clause).

    • typestring (enum)required

      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_idstringrequired
    • source"builtin" | "company"required
    • versionintegerrequired
    • namestringrequired
    • variant_countrystring (enum)required

      Whose rules ran: the person's country, or EU.

      One of: PT, ES, FR, DE, IT, NL, EU.

    • notestringrequired

      What the law says there (English; the app translates it).

    • confidence"verified" | "medium" | "uncertain"required
    • sourcesobject[]required
      2 fields
      • urlstringrequired
      • articlestringrequired
    • other_countrybooleanrequired

      Your clause was written for another country's rules; it still runs the person's.

  • style"international" | "continental"required

    The style it is shown in.

  • style_default"international" | "continental"required

    The style it gets without a choice: the template's default, else the company's, else the country's.

  • style_hintsobjectrequired

    A short example of each style's numbering in the document's language, e.g. "1. · 1.1 · (a)".

    2 fields
    • internationalstringrequired
    • continentalstringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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
        }
      }
    }
  }
}'
Response
{
  "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_check on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • template_idstring
  • versioninteger

    At least 1.

  • bodiesobject
    6 fields
    • enobject
      2 fields
      • titlestringrequired

        The generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".

        1–200 characters.

      • bodystringrequired

        The 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.

    • ptobject
      2 fields
      • titlestringrequired

        The generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".

        1–200 characters.

      • bodystringrequired

        The 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.

    • esobject
      2 fields
      • titlestringrequired

        The generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".

        1–200 characters.

      • bodystringrequired

        The 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.

    • frobject
      2 fields
      • titlestringrequired

        The generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".

        1–200 characters.

      • bodystringrequired

        The 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.

    • deobject
      2 fields
      • titlestringrequired

        The generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".

        1–200 characters.

      • bodystringrequired

        The 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.

    • itobject
      2 fields
      • titlestringrequired

        The generated document's title; may use public fields only, e.g. "Employment contract – {{person.full_name}}".

        1–200 characters.

      • bodystringrequired

        The 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[]required
    8 fields
    • language"en" | "pt" | "es" | "fr" | "de" | "it"required
    • field"title" | "body"required
    • lineintegerrequired
    • colintegerrequired
    • codestringrequired
    • messagestringrequired

      English; the app translates by code.

    • severity"error" | "warning"required
    • paramsobject
  • tier"public" | "job" | "private" | "pay"required
  • fieldsstring[]required
  • lawobject[]required
    11 fields
    • countrystringrequired

      The country whose rules apply (EU: Directive 2019/1152, for any other country).

    • reviewedbooleanrequired

      A local employment lawyer checked this country's rules.

    • coveredobject[]required
      6 fields
      • idstringrequired
      • labelstringrequired

        English; the app translates it.

      • requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
      • notestring | nullrequired
    • missingobject[]required

      Required items the template does not cover.

      6 fields
      • idstringrequired
      • labelstringrequired

        English; the app translates it.

      • requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
      • notestring | nullrequired
    • optionalobject[]required

      Items needed only sometimes (fixed-term, probation…) that it does not cover.

      6 fields
      • idstringrequired
      • labelstringrequired

        English; the app translates it.

      • requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
      • notestring | nullrequired
    • manualobject[]required

      Items Bizisy cannot check by field: make sure the text says them.

      6 fields
      • idstringrequired
      • labelstringrequired

        English; the app translates it.

      • requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
      • notestring | nullrequired
    • signatureobjectrequired
      6 fields
      • min_level"none" | "simple" | "advanced" | "qualified" | "wet"required

        The lowest signature level that makes it valid (wet: printed and signed by hand).

      • whostring[]required
      • notestringrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required

        Only verified rules block; others warn.

      • alternativesstring[]required
    • deliveryobjectrequired
      3 fields
      • deadlinestringrequired

        before_start, on_start, days_after_start, by_effective_date, before_end, on_last_day, on_request or none.

      • proof_requiredbooleanrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
    • languageobjectrequired
      3 fields
      • mandatorystring | nullrequired
      • defaultstring | nullrequired
      • translation_allowedbooleanrequired
    • dueobject[]required

      For a person: by when each part must reach them.

      2 fields
      • partstringrequired
      • duestringrequired
    • disclaimerstringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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"
  ]
}'
Response
{
  "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_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

  • approval"none" | "hr" | "owner"required

    Who 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).

  • approversintegerrequired

    How many logins could approve under the current rule (besides whoever asks).

  • style"international" | "continental"required

    The 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 | nullrequired
  • can_changebooleanrequired

    Owners and admins change it, in the web app.

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/documents/templates.settings.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "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_update on HR Assistant
Preview
?dry_run=true runs 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"required

    Who 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).

  • approversintegerrequired

    How many logins could approve under the current rule (besides whoever asks).

  • style"international" | "continental"required

    The 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 | nullrequired
  • can_changebooleanrequired

    Owners and admins change it, in the web app.

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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}'
Response
{
  "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_decide on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • template_idstringrequired
  • decision"approve" | "reject"required
  • commentstring

    Up to 500 characters.

Returns

  • template_idstringrequired
  • decision"approve" | "reject"required
  • versioninteger | nullrequired

    The version published (approve).

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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."}'
Response
{
  "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_withdraw on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • template_idstringrequired

Returns

  • template_idstringrequired
  • withdrawnbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_approvals on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • template_idstring

Returns

  • approvalsobject[]required
    14 fields
    • template_idstringrequired
    • namestringrequired
    • kindstringrequired
    • versionintegerrequired
    • tier"public" | "job" | "private" | "pay"required
    • asked_atstringrequired
    • asked_byobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • approvers"hr" | "owner"required
    • can_decidebooleanrequired
    • why_not"machine" | "yours" | "role" | "decided"required

      Why you can't decide it: you asked or changed it (yours), your role, or an API key / AI assistant (machine).

    • previous_versioninteger | nullrequired
    • body_hiddenbooleanrequired

      It uses pay details you can't see: what changed is not shown.

    • changesobject[]required
      7 fields
      • language"en" | "pt" | "es" | "fr" | "de" | "it"required
      • status"changed" | "added" | "removed" | "same"required

        added: a new language; removed: a language taken out.

      • titleobject | nullrequired

        When the title changed.

        2 fields
        • beforestring | nullrequired
        • afterstring | nullrequired
      • linesobject[]required

        The body, line by line: same, add, del; skip folds unchanged lines.

        4 fields (one of several shapes)

        Option 1

        • op"same" | "add" | "del"required
        • textstringrequired

        Option 2

        • op"skip"required
        • countintegerrequired
      • addedintegerrequired
      • removedintegerrequired
      • too_longbooleanrequired
    • details_changedstring[]required

      Other settings that change: name, category, countries, signers, visibility, slots, style.

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/documents/templates.approvals \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template_id":"tpl1"}'
Response
{
  "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_start on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • namestringrequired

    1–200 characters.

  • sizeintegerrequired

    From 0 to 5000000.

  • content_type"application/vnd.openxmlformats-officedocument.wordprocessingml.document"required

    A Word document (.docx); .doc, .docm, PDF and others are refused.

  • sha256stringrequired

    Pattern ^[0-9a-f]{64}$.

Returns

  • file_idstringrequired
  • uploadobject | nullrequired

    null on a dry run.

    4 fields
    • urlstringrequired
    • method"PUT"required
    • headersobjectrequired
    • resumablefalserequired
  • expires_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"
}'
Response
{
  "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_docx on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • file_idstringrequired

    1–64 characters.

  • language"en" | "pt" | "es" | "fr" | "de" | "it"required

    The language the document is written in.

  • kindstring (enum)required

    One of: contract_open, contract_fixed, contract_part_time, statement, amendment, change_notice, end_notice, certificate, declaration, policy, letter, offer_letter, pay_review_letter.

  • namestring

    Default: the title found in the file.

    1–120 characters.

  • categorystring

    Default: 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.

  • mappingsobject

    Candidate id → the field it becomes (e.g. {"c1": "person.full_name"}); null or left out: kept as text.

Returns

  • conversionobjectrequired
    7 fields
    • textstringrequired

      The converted text (Markdown-lite), with the mappings applied.

    • titlestringrequired

      The title found (the first heading or line).

    • originalstring[]required

      The Word file's paragraphs as plain text, to compare side by side.

    • candidatesobject[]required
      8 fields
      • idstringrequired

        Send it back in mappings with the field it should become.

      • kindstring (enum)required

        How 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.

      • rawstringrequired

        As it appears in the converted text.

      • labelstringrequired

        The words it carries (for a blank: the words before it); may be empty.

      • countintegerrequired

        How many times it appears.

      • contextstringrequired

        The line around its first appearance.

      • suggestionsobject[]required

        Fields it may be, best first (none: no field matched; keep it as text or pick one).

        2 fields
        • pathstringrequired
        • scorenumberrequired

          0–1: how well the label matches the field's usual names.

      • mappedstring | nullrequired

        The field it became (real run) or will become (dry run with mappings); null: kept as text.

    • warningsobject[]required

      What was not imported (images, comments, footnotes, headers and footers, tracked changes accepted…).

      2 fields
      • codestringrequired
      • messagestringrequired

        English; the app translates it by code.

    • statsobjectrequired
      5 fields
      • paragraphsintegerrequired
      • headingsintegerrequired
      • listsintegerrequired
      • tablesintegerrequired
      • page_breaksintegerrequired
    • problemsobject[]required

      Lint of the result in that language: errors refuse creating the draft.

      8 fields
      • language"en" | "pt" | "es" | "fr" | "de" | "it"required
      • field"title" | "body"required
      • lineintegerrequired
      • colintegerrequired
      • codestringrequired
      • messagestringrequired

        English; the app translates by code.

      • severity"error" | "warning"required
      • paramsobject
  • template_idstring | nullrequired

    The draft made (null on a dry run).

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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
  }
}'
Response
{
  "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_docx on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • file_idstringrequired

    1–64 characters.

  • language"en" | "pt" | "es" | "fr" | "de" | "it"required
  • typestring (enum)required

    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.

  • countrystringrequired

    Pattern ^[A-Z]{2}$.

  • namestring

    1–120 characters.

  • mappingsobject

    Candidate id → the field it becomes (e.g. {"c1": "person.full_name"}); null or left out: kept as text.

Returns

  • conversionobjectrequired
    7 fields
    • textstringrequired

      The converted text (Markdown-lite), with the mappings applied.

    • titlestringrequired

      The title found (the first heading or line).

    • originalstring[]required

      The Word file's paragraphs as plain text, to compare side by side.

    • candidatesobject[]required
      8 fields
      • idstringrequired

        Send it back in mappings with the field it should become.

      • kindstring (enum)required

        How 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.

      • rawstringrequired

        As it appears in the converted text.

      • labelstringrequired

        The words it carries (for a blank: the words before it); may be empty.

      • countintegerrequired

        How many times it appears.

      • contextstringrequired

        The line around its first appearance.

      • suggestionsobject[]required

        Fields it may be, best first (none: no field matched; keep it as text or pick one).

        2 fields
        • pathstringrequired
        • scorenumberrequired

          0–1: how well the label matches the field's usual names.

      • mappedstring | nullrequired

        The field it became (real run) or will become (dry run with mappings); null: kept as text.

    • warningsobject[]required

      What was not imported (images, comments, footnotes, headers and footers, tracked changes accepted…).

      2 fields
      • codestringrequired
      • messagestringrequired

        English; the app translates it by code.

    • statsobjectrequired
      5 fields
      • paragraphsintegerrequired
      • headingsintegerrequired
      • listsintegerrequired
      • tablesintegerrequired
      • page_breaksintegerrequired
    • problemsobject[]required

      Lint of the result in that language: errors refuse creating the draft.

      8 fields
      • language"en" | "pt" | "es" | "fr" | "de" | "it"required
      • field"title" | "body"required
      • lineintegerrequired
      • colintegerrequired
      • codestringrequired
      • messagestringrequired

        English; the app translates by code.

      • severity"error" | "warning"required
      • paramsobject
  • clause_idstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"
  }
}'
Response
{
  "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_generate on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • template_idstringrequired
  • versioninteger

    At least 1.

  • language"en" | "pt" | "es" | "fr" | "de" | "it"
  • person_idsstring[]

    1–200 items.

  • group_idstring
  • overridesobject
  • clausesobject

    The 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
    • slotsobject

      Per clause slot, the clauses in order (an empty list: none). A slot left out gets its defaults.

    • fixedobject

      Fixed clauses ({{clause "type"}}): their typed fields, or another clause of that type.

      16 fields
      • non_competeobjectrequired
        2 fields
        • clause_idstring

          1–100 characters.

        • fieldsobject
      • non_solicitationobjectrequired
        2 fields
        • clause_idstring

          1–100 characters.

        • fieldsobject
      • probationobjectrequired
        2 fields
        • clause_idstring

          1–100 characters.

        • fieldsobject
      • training_repaymentobjectrequired
        2 fields
        • clause_idstring

          1–100 characters.

        • fieldsobject
      • remote_workobjectrequired
        2 fields
        • clause_idstring

          1–100 characters.

        • fieldsobject
      • exclusivityobjectrequired
        2 fields
        • clause_idstring

          1–100 characters.

        • fieldsobject
      • confidentialityobjectrequired
        2 fields
        • clause_idstring

          1–100 characters.

        • fieldsobject
      • ip_inventionsobjectrequired
        2 fields
        • clause_idstring

          1–100 characters.

        • fieldsobject
      • mobilityobjectrequired
        2 fields
        • clause_idstring

          1–100 characters.

        • fieldsobject
      • overtime_includedobjectrequired
        2 fields
        • clause_idstring

          1–100 characters.

        • fieldsobject
      • noticeobjectrequired
        2 fields
        • clause_idstring

          1–100 characters.

        • fieldsobject
      • garden_leaveobjectrequired
        2 fields
        • clause_idstring

          1–100 characters.

        • fieldsobject
      • equipmentobjectrequired
        2 fields
        • clause_idstring

          1–100 characters.

        • fieldsobject
      • monitoring_noticeobjectrequired
        2 fields
        • clause_idstring

          1–100 characters.

        • fieldsobject
      • collective_agreementobjectrequired
        2 fields
        • clause_idstring

          1–100 characters.

        • fieldsobject
      • pay_extra_monthsobjectrequired
        2 fields
        • clause_idstring

          1–100 characters.

        • fieldsobject
    • per_personobject

      Per 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.

  • draftboolean

    Default 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_idstring

    Internal: the background run this call is a step of (set by Bizisy, never by you).

  • sendobject
    4 fields
    • method"tool" | "autenticacao_gov" | "bizisy_accept"
    • level"simple" | "advanced" | "qualified"
    • remindersobject | null
      2 fields
      • interval_days1 | 2 | 7 | 14required
      • maxintegerrequired

        From 1 to 10.

    • expires_onstring

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

Returns

7 fields
  • template_idstringrequired
  • versionintegerrequired
  • peopleobject[]required
    15 fields
    • person_idstringrequired
    • namestring | nullrequired

      The person's name (null when not found).

    • language"en" | "pt" | "es" | "fr" | "de" | "it"required
    • readybooleanrequired

      Nothing missing or withheld: a real run makes this person's document.

    • missingstring[]required

      Fields with no value on lines that stay: fill them on the profile, or pass overrides for this document only.

    • droppedstring[]required

      Lines left out because all their fields are empty.

    • withheldstring[]required

      Fields you may not see for this person: you can't generate this template for them.

    • problemstring | nullrequired

      Why this person can't get the document (not found, a field withheld).

    • style"international" | "continental"required

      The document style their document is made in (the one chosen, else the template's, the company's, their country's).

    • lawobject | nullrequired
      6 fields
      • countrystringrequired
      • min_level"none" | "simple" | "advanced" | "qualified" | "wet"required

        The lowest signature level the law accepts for this document in their country.

      • level_okboolean | nullrequired

        With send: the level it would be sent with meets it (null without send).

      • blockingbooleanrequired

        A verified rule: sending below it is refused.

      • notestring | nullrequired
      • raised_by_clauseboolean

        A 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
      • okbooleanrequired

        No block: the clause may go in the document.

      • countrystring (enum)required

        Whose 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[]required

        The law Bizisy treats as settled is broken: the document is refused with it.

        6 fields
        • rulestringrequired
        • messagestringrequired

          English with {params}; the app translates it.

        • paramsobject | nullrequired
        • fieldstring | nullrequired

          The typed field it is about.

        • sourceobjectrequired
          2 fields
          • urlstringrequired
          • articlestringrequired
        • confidence"verified" | "medium" | "uncertain"required
      • warnsobject[]required

        Less certain rules and reminders: the document is made, check with your lawyer.

        6 fields
        • rulestringrequired
        • messagestringrequired

          English with {params}; the app translates it.

        • paramsobject | nullrequired
        • fieldstring | nullrequired

          The typed field it is about.

        • sourceobjectrequired
          2 fields
          • urlstringrequired
          • articlestringrequired
        • confidence"verified" | "medium" | "uncertain"required
      • raises_toobject | nullrequired

        The signature level the clause needs (e.g. a German non-compete: qualified or by hand).

        3 fields
        • level"none" | "simple" | "advanced" | "qualified" | "wet"required
        • confidence"verified" | "medium" | "uncertain"required
        • sourceobject | nullrequired
          2 fields
          • urlstringrequired
          • articlestringrequired
      • tasksobject[]required

        To do once signed (Italy: file the smart-working agreement within 5 days).

        4 fields
        • idstringrequired
        • labelstringrequired
        • days_after_startintegerrequired
        • sourceobjectrequired
          2 fields
          • urlstringrequired
          • articlestringrequired
      • fieldsobjectrequired

        The fields as checked (defaults filled in).

      • slotstring | nullrequired

        The slot it is in (null: a fixed clause).

      • typestring (enum)required

        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_idstringrequired
      • source"builtin" | "company"required
      • versionintegerrequired
      • namestringrequired
      • variant_countrystring (enum)required

        Whose rules ran: the person's country, or EU.

        One of: PT, ES, FR, DE, IT, NL, EU.

      • notestringrequired

        What the law says there (English; the app translates it).

      • confidence"verified" | "medium" | "uncertain"required
      • sourcesobject[]required
        2 fields
        • urlstringrequired
        • articlestringrequired
      • other_countrybooleanrequired

        Your clause was written for another country's rules; it still runs the person's.

    • preview_htmlstring | nullrequired

      Dry runs: the document as HTML for the first 20 people (documents_templates_preview for the rest).

    • document_idstring | nullrequired
    • signature_idstring | nullrequired
    • prepared_idstring | null

      A draft (HR only until sent): send, edit or discard it with documents_prepared_decide.

  • createdintegerrequired
  • sentintegerrequired
  • runobject | null

    More than 20 people: the documents are made in the background; follow it with documents_generate_run_get.

    3 fields
    • idstringrequired
    • status"working" | "done" | "failed" | "cancelled"required
    • totalintegerrequired
  • today_leftintegerrequired

    Documents 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
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": []
        }
      }
    }
  }
}'
Response
{
  "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_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • template_idstring
  • versioninteger

    At least 1.

  • person_idstring
  • clause_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_idstring
  • clause_versioninteger

    With clause_id.

    At least 1.

  • limitinteger

    Default 200.

    From 1 to 500.

Returns

  • documentsobject[]required
    9 fields
    • documentobjectrequired
      19 fields
      • idstringrequired
      • titlestringrequired
      • categorystringrequired
      • subjectobjectrequired
        3 fields (one of several shapes)

        Option 1

        • kind"person"required
        • personobject | nullrequired
          2 fields
          • idstringrequired
          • namestringrequired

        Option 2

        • kind"company"required
      • visibilitystring (enum)required

        One of: hr, hr_person, hr_person_manager, everyone, managers, hr, accountant.

      • uploaded_by"hr" | "self"required

        self: the person added it themself ("From me", or a custom field they fill in).

      • fieldobject | nullrequired

        A custom file field's file (org_fields_list): its visibility follows the field's tier; replace or remove it through the field.

        2 fields
        • keystringrequired
        • labelstringrequired
      • expires_onstring | nullrequired
      • notesstring | nullrequired

        null when you only see metadata.

      • fileobjectrequired
        4 fields
        • namestring | nullrequired

          The original file name; null when you only see metadata.

        • sizeintegerrequired
        • content_typestringrequired
        • previewablebooleanrequired

          The web app can show it (PDF, PNG, JPEG, WebP).

      • access"full" | "metadata"required

        metadata: 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 | nullrequired

        A signed copy or signature audit trail the e-signature tool handed back: the original document. null for other documents.

        2 fields
        • document_idstringrequired
        • kind"signed" | "audit_trail"required
      • signatureobject | null

        The latest signature request (lists only): status, level and how many have signed.

        6 fields
        • idstringrequired
        • statusstring (enum)required

          One of: queued, sending, ongoing, done, declined, expired, canceled, failed.

        • level"simple" | "advanced" | "qualified"required
        • signedintegerrequired
        • totalintegerrequired
        • your_turnbooleanrequired

          You are the signer the e-signature tool is waiting for (check your email from it).

      • generated_fromobject | null

        Made from a document template: which one, its version, language and style (documents_templates_get). null for uploaded documents.

        4 fields
        • template_idstringrequired
        • versionintegerrequired
        • languagestringrequired
        • style"international" | "continental"required

          The document style it was made in (international or continental); null for documents made before styles existed.

      • draftobject | null

        A 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_idstringrequired
        • visibility"hr" | "hr_person" | "hr_person_manager"required
      • deliveryobject | null

        Proof 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"required
        • sent_atstringrequired
        • opened_atstring | nullrequired
        • acknowledged_atstring | nullrequired
        • handed_over_onstring | nullrequired
      • status"pending" | "ready"required
      • created_atstringrequired
      • updated_atstringrequired
    • template_idstringrequired
    • versionintegerrequired
    • language"en" | "pt" | "es" | "fr" | "de" | "it"required
    • kindstring (enum)required

      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)required

      One of: manual, bulk, hire, rehire, change, request, current_staff, fixed_term_end, leaving, pay_review.

    • signatureobject | nullrequired
      6 fields
      • idstringrequired
      • statusstring (enum)required

        One of: queued, sending, ongoing, done, declined, expired, canceled, failed.

      • level"simple" | "advanced" | "qualified"required
      • signedintegerrequired
      • totalintegerrequired
      • your_turnbooleanrequired

        You are the signer the e-signature tool is waiting for (check your email from it).

    • clausesobject[]required

      The clauses in it: type, the country whose rules ran, the clause and its version.

      5 fields
      • slotstring | nullrequired
      • typestring (enum)required

        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.

      • countrystringrequired
      • clause_idstringrequired
      • versionintegerrequired
    • style"international" | "continental"required

      The document style it was made in (null: made before styles existed).

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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}'
Response
{
  "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_export on HR Assistant, My Workplace
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • document_idstring
  • template_idstring
  • versioninteger

    At least 1.

  • language"en" | "pt" | "es" | "fr" | "de" | "it"
  • format"pdf" | "docx"required

Returns

  • urlstring | nullrequired

    Signed URL valid for 5 minutes, downloads as an attachment. null on a dry run. Never store or share it.

  • expires_atstring | nullrequired
  • file_namestringrequired
  • content_typestringrequired
  • sizeintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • run_idstringrequired

Returns

9 fields
  • idstringrequired
  • status"working" | "done" | "failed" | "cancelled"required
  • totalintegerrequired
  • doneintegerrequired
  • createdintegerrequired

    Documents made so far.

  • problemsobject[]required

    People whose document could not be made, and why.

    2 fields
    • person_idstringrequired
    • problemstringrequired
  • errorstring | nullrequired
  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_cancel on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • run_idstringrequired

Returns

9 fields
  • idstringrequired
  • status"working" | "done" | "failed" | "cancelled"required
  • totalintegerrequired
  • doneintegerrequired
  • createdintegerrequired

    Documents made so far.

  • problemsobject[]required

    People whose document could not be made, and why.

    2 fields
    • person_idstringrequired
    • problemstringrequired
  • errorstring | nullrequired
  • created_atstringrequired
  • updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

No input: send {}.

Returns

9 fields
  • statementobjectrequired
    3 fields
    • onbooleanrequired

      Prepare the written statement when someone is hired (default on: a legal duty in every EU country).

    • auto_sendbooleanrequired

      Send it by itself on its legal deadline when HR has not acted (default on).

    • template_idstring | nullrequired

      null: the built-in for each person's country.

  • change_noticeobjectrequired
    2 fields
    • onbooleanrequired

      Prepare 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"required

    My workspace "Ask for my written statement": off, review (prepared for HR, default) or instant (sent at once).

  • de_sectorstring | nullrequired

    Germany: the company's SchwarzArbG §2a sector, whose statements are printed and signed by hand.

  • amendmentobjectrequired
    2 fields
    • onbooleanrequired

      Prepare an amendment (addendum) to the contract when an approved change takes effect (default off; always waits for HR).

    • template_idstring | nullrequired
  • fixed_termobjectrequired
    3 fields
    • onbooleanrequired

      Fixed-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 | nullrequired
    • renewal_template_idstring | nullrequired
  • certificateobjectrequired
    2 fields
    • onbooleanrequired

      Prepare 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
  • declarationsobjectrequired
    4 fields
    • employment"off" | "review" | "instant"required

      My workspace "Ask for a document": the employment declaration: off, review (prepared for HR, default) or instant.

    • salary"off" | "review" | "instant"required

      The salary declaration (it shows pay): off by default, review or instant.

    • employment_template_idstring | nullrequired
    • salary_template_idstring | nullrequired
  • sectorsobject[]required

    The §2a sectors (labels in English; the app translates them).

    2 fields
    • idstringrequired
    • labelstringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/documents/automations.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Response
{
  "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_set on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • statementobject
    3 fields
    • onboolean
    • auto_sendboolean
    • template_idstring | null
  • change_noticeobject
    2 fields
    • onboolean
    • template_idstring | null
  • self_request"off" | "review" | "instant"
  • de_sectorstring | null

    1–60 characters.

  • amendmentobject
    2 fields
    • onboolean
    • template_idstring | null
  • fixed_termobject
    3 fields
    • onboolean
    • end_notice_template_idstring | null
    • renewal_template_idstring | null
  • certificateobject
    2 fields
    • onboolean
    • template_idstring | null
  • declarationsobject
    4 fields
    • employment"off" | "review" | "instant"
    • salary"off" | "review" | "instant"
    • employment_template_idstring | null
    • salary_template_idstring | null

Returns

9 fields
  • statementobjectrequired
    3 fields
    • onbooleanrequired

      Prepare the written statement when someone is hired (default on: a legal duty in every EU country).

    • auto_sendbooleanrequired

      Send it by itself on its legal deadline when HR has not acted (default on).

    • template_idstring | nullrequired

      null: the built-in for each person's country.

  • change_noticeobjectrequired
    2 fields
    • onbooleanrequired

      Prepare 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"required

    My workspace "Ask for my written statement": off, review (prepared for HR, default) or instant (sent at once).

  • de_sectorstring | nullrequired

    Germany: the company's SchwarzArbG §2a sector, whose statements are printed and signed by hand.

  • amendmentobjectrequired
    2 fields
    • onbooleanrequired

      Prepare an amendment (addendum) to the contract when an approved change takes effect (default off; always waits for HR).

    • template_idstring | nullrequired
  • fixed_termobjectrequired
    3 fields
    • onbooleanrequired

      Fixed-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 | nullrequired
    • renewal_template_idstring | nullrequired
  • certificateobjectrequired
    2 fields
    • onbooleanrequired

      Prepare 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
  • declarationsobjectrequired
    4 fields
    • employment"off" | "review" | "instant"required

      My workspace "Ask for a document": the employment declaration: off, review (prepared for HR, default) or instant.

    • salary"off" | "review" | "instant"required

      The salary declaration (it shows pay): off by default, review or instant.

    • employment_template_idstring | nullrequired
    • salary_template_idstring | nullrequired
  • sectorsobject[]required

    The §2a sectors (labels in English; the app translates them).

    2 fields
    • idstringrequired
    • labelstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"
  }
}'
Response
{
  "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_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • person_idstringrequired

Returns

  • person_idstringrequired
  • electronicbooleanrequired
  • atstring | nullrequired
  • by"self" | "hr"required

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

Response
{
  "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_set on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • person_idstringrequired
  • electronicbooleanrequired

Returns

  • person_idstringrequired
  • electronicbooleanrequired
  • atstring | nullrequired
  • by"self" | "hr"required

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

Response
{
  "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_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • status"prepared" | "sent" | "discarded" | "all"

    Default prepared.

  • person_idstring
  • 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.

  • limitinteger

    Default 200.

    From 1 to 500.

Returns

  • preparedobject[]required
    22 fields
    • idstringrequired
    • personobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • kindstring (enum)required

      statement (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)required

      hire, 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"required
    • due_onstring | nullrequired

      The legal deadline to give it to the person (null: none).

    • overduebooleanrequired
    • partsobject[]required

      Deadlines per part (e.g. Germany: day 1, day 7, one month).

      2 fields
      • partstringrequired
      • duestringrequired
    • deliveryobjectrequired

      electronic (My workspace, email, receipt to confirm) or print (NL without consent, a DE §2a sector).

      2 fields
      • method"electronic" | "print"required
      • why"nl_no_consent" | "de_sector" | "chosen" | "no_consent"required
    • employer_qesbooleanrequired

      NL: sent electronically, it must carry the employer's qualified electronic signature: send a signed copy (signed_document_id).

    • template_idstring | nullrequired

      null: the company's choice for the kind, else the country's built-in.

    • document_idstring | nullrequired

      The document once rendered (HR only until sent).

    • changed_fieldsstring[]required

      Change notices: the fields that changed (values only in the app, in the document).

    • effectivestring | nullrequired

      Change notices: the day the change takes effect.

    • blockedobject | nullrequired

      Why 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
      • onstringrequired
      • whystring (enum)required

        clause: 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 | nullrequired

      Proof of delivery: when it went, how, when the person first opened it and when they confirmed receipt.

      6 fields
      • atstringrequired
      • by"hr" | "auto" | "self"required
      • method"electronic" | "print"required
      • handed_over_onstring | nullrequired
      • opened_atstring | nullrequired
      • acknowledged_atstring | nullrequired
    • discarded_atstring | nullrequired
    • created_atstringrequired
    • variant"renewal" | "reference" | "salary" | "employment"required

      Step 4: renewal (an amendment renewing a fixed-term contract), reference (DE qualified reference), salary or employment (declarations); null: the kind's own document.

    • warningsobject[]required

      What 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"required
      • daysinteger | nullrequired
      • bystring | nullrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
    • decisionobject | nullrequired

      End 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"required
      • new_end_datestring | nullrequired
      • termsstring | nullrequired
    • contract_endstring | nullrequired

      End notices: the contract's end date.

  • countsobjectrequired
    3 fields
    • preparedintegerrequired
    • overdueintegerrequired
    • due_soonintegerrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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}'
Response
{
  "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_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • prepared_idstringrequired

Returns

  • preparedobjectrequired
    22 fields
    • idstringrequired
    • personobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • kindstring (enum)required

      statement (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)required

      hire, 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"required
    • due_onstring | nullrequired

      The legal deadline to give it to the person (null: none).

    • overduebooleanrequired
    • partsobject[]required

      Deadlines per part (e.g. Germany: day 1, day 7, one month).

      2 fields
      • partstringrequired
      • duestringrequired
    • deliveryobjectrequired

      electronic (My workspace, email, receipt to confirm) or print (NL without consent, a DE §2a sector).

      2 fields
      • method"electronic" | "print"required
      • why"nl_no_consent" | "de_sector" | "chosen" | "no_consent"required
    • employer_qesbooleanrequired

      NL: sent electronically, it must carry the employer's qualified electronic signature: send a signed copy (signed_document_id).

    • template_idstring | nullrequired

      null: the company's choice for the kind, else the country's built-in.

    • document_idstring | nullrequired

      The document once rendered (HR only until sent).

    • changed_fieldsstring[]required

      Change notices: the fields that changed (values only in the app, in the document).

    • effectivestring | nullrequired

      Change notices: the day the change takes effect.

    • blockedobject | nullrequired

      Why 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
      • onstringrequired
      • whystring (enum)required

        clause: 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 | nullrequired

      Proof of delivery: when it went, how, when the person first opened it and when they confirmed receipt.

      6 fields
      • atstringrequired
      • by"hr" | "auto" | "self"required
      • method"electronic" | "print"required
      • handed_over_onstring | nullrequired
      • opened_atstring | nullrequired
      • acknowledged_atstring | nullrequired
    • discarded_atstring | nullrequired
    • created_atstringrequired
    • variant"renewal" | "reference" | "salary" | "employment"required

      Step 4: renewal (an amendment renewing a fixed-term contract), reference (DE qualified reference), salary or employment (declarations); null: the kind's own document.

    • warningsobject[]required

      What 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"required
      • daysinteger | nullrequired
      • bystring | nullrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
    • decisionobject | nullrequired

      End 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"required
      • new_end_datestring | nullrequired
      • termsstring | nullrequired
    • contract_endstring | nullrequired

      End notices: the contract's end date.

  • checkobjectrequired
    9 fields
    • missingstring[]required

      Fields with no value: nothing is sent with a blank (fill them, or edit with overrides).

    • droppedstring[]required
    • withheldstring[]required
    • templateobject | nullrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • versionintegerrequired
    • language"en" | "pt" | "es" | "fr" | "de" | "it"required
    • countrystring | nullrequired
    • preview_htmlstring | nullrequired
    • problemstring | nullrequired

      Why it can't be made now (person gone, template archived…).

    • style"international" | "continental"required

      The 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
curl https://api.bizisy.com/v1/documents/prepared.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prepared_id":"prep1"}'
Response
{
  "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_decide on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • prepared_idstringrequired
  • action"send" | "edit" | "discard"required
  • method"electronic" | "print"
  • handed_over_onstring

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

  • signed_document_idstring
  • overridesobject
  • template_idstring | null
  • language"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

  • preparedobjectrequired
    22 fields
    • idstringrequired
    • personobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • kindstring (enum)required

      statement (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)required

      hire, 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"required
    • due_onstring | nullrequired

      The legal deadline to give it to the person (null: none).

    • overduebooleanrequired
    • partsobject[]required

      Deadlines per part (e.g. Germany: day 1, day 7, one month).

      2 fields
      • partstringrequired
      • duestringrequired
    • deliveryobjectrequired

      electronic (My workspace, email, receipt to confirm) or print (NL without consent, a DE §2a sector).

      2 fields
      • method"electronic" | "print"required
      • why"nl_no_consent" | "de_sector" | "chosen" | "no_consent"required
    • employer_qesbooleanrequired

      NL: sent electronically, it must carry the employer's qualified electronic signature: send a signed copy (signed_document_id).

    • template_idstring | nullrequired

      null: the company's choice for the kind, else the country's built-in.

    • document_idstring | nullrequired

      The document once rendered (HR only until sent).

    • changed_fieldsstring[]required

      Change notices: the fields that changed (values only in the app, in the document).

    • effectivestring | nullrequired

      Change notices: the day the change takes effect.

    • blockedobject | nullrequired

      Why 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
      • onstringrequired
      • whystring (enum)required

        clause: 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 | nullrequired

      Proof of delivery: when it went, how, when the person first opened it and when they confirmed receipt.

      6 fields
      • atstringrequired
      • by"hr" | "auto" | "self"required
      • method"electronic" | "print"required
      • handed_over_onstring | nullrequired
      • opened_atstring | nullrequired
      • acknowledged_atstring | nullrequired
    • discarded_atstring | nullrequired
    • created_atstringrequired
    • variant"renewal" | "reference" | "salary" | "employment"required

      Step 4: renewal (an amendment renewing a fixed-term contract), reference (DE qualified reference), salary or employment (declarations); null: the kind's own document.

    • warningsobject[]required

      What 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"required
      • daysinteger | nullrequired
      • bystring | nullrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
    • decisionobject | nullrequired

      End 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"required
      • new_end_datestring | nullrequired
      • termsstring | nullrequired
    • contract_endstring | nullrequired

      End notices: the contract's end date.

  • checkobject | nullrequired
    9 fields
    • missingstring[]required

      Fields with no value: nothing is sent with a blank (fill them, or edit with overrides).

    • droppedstring[]required
    • withheldstring[]required
    • templateobject | nullrequired
      3 fields
      • idstringrequired
      • namestringrequired
      • versionintegerrequired
    • language"en" | "pt" | "es" | "fr" | "de" | "it"required
    • countrystring | nullrequired
    • preview_htmlstring | nullrequired
    • problemstring | nullrequired

      Why it can't be made now (person gone, template archived…).

    • style"international" | "continental"required

      The 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
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"
}'
Response
{
  "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_prepare on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • person_idsstring[]

    1–500 items.

  • all_currentboolean

Returns

  • preparedintegerrequired
  • skippedintegerrequired
  • cappedbooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"]}'
Response
{
  "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_create on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • person_idstringrequired
  • kind"amendment" | "end_notice" | "certificate" | "declaration"required
  • variant"renewal" | "reference" | "salary" | "employment"
  • effective_datestring

    Amendments: the day the change took (or takes) effect; default their latest change.

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

  • template_idstring | null
  • language"en" | "pt" | "es" | "fr" | "de" | "it"

Returns

  • preparedobjectrequired
    22 fields
    • idstringrequired
    • personobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • kindstring (enum)required

      statement (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)required

      hire, 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"required
    • due_onstring | nullrequired

      The legal deadline to give it to the person (null: none).

    • overduebooleanrequired
    • partsobject[]required

      Deadlines per part (e.g. Germany: day 1, day 7, one month).

      2 fields
      • partstringrequired
      • duestringrequired
    • deliveryobjectrequired

      electronic (My workspace, email, receipt to confirm) or print (NL without consent, a DE §2a sector).

      2 fields
      • method"electronic" | "print"required
      • why"nl_no_consent" | "de_sector" | "chosen" | "no_consent"required
    • employer_qesbooleanrequired

      NL: sent electronically, it must carry the employer's qualified electronic signature: send a signed copy (signed_document_id).

    • template_idstring | nullrequired

      null: the company's choice for the kind, else the country's built-in.

    • document_idstring | nullrequired

      The document once rendered (HR only until sent).

    • changed_fieldsstring[]required

      Change notices: the fields that changed (values only in the app, in the document).

    • effectivestring | nullrequired

      Change notices: the day the change takes effect.

    • blockedobject | nullrequired

      Why 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
      • onstringrequired
      • whystring (enum)required

        clause: 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 | nullrequired

      Proof of delivery: when it went, how, when the person first opened it and when they confirmed receipt.

      6 fields
      • atstringrequired
      • by"hr" | "auto" | "self"required
      • method"electronic" | "print"required
      • handed_over_onstring | nullrequired
      • opened_atstring | nullrequired
      • acknowledged_atstring | nullrequired
    • discarded_atstring | nullrequired
    • created_atstringrequired
    • variant"renewal" | "reference" | "salary" | "employment"required

      Step 4: renewal (an amendment renewing a fixed-term contract), reference (DE qualified reference), salary or employment (declarations); null: the kind's own document.

    • warningsobject[]required

      What 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"required
      • daysinteger | nullrequired
      • bystring | nullrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
    • decisionobject | nullrequired

      End 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"required
      • new_end_datestring | nullrequired
      • termsstring | nullrequired
    • contract_endstring | nullrequired

      End notices: the contract's end date.

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"
}'
Response
{
  "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_contract on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key prevents a second run, but the result is never stored (it holds a secret or personal data): a retry gets a 409 that points to Activity

Input

  • prepared_idstringrequired
  • outcome"renew" | "permanent" | "end"required
  • new_end_datestring

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

  • termsstring

    What 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

  • preparedobjectrequired
    22 fields
    • idstringrequired
    • personobject | nullrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • kindstring (enum)required

      statement (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)required

      hire, 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"required
    • due_onstring | nullrequired

      The legal deadline to give it to the person (null: none).

    • overduebooleanrequired
    • partsobject[]required

      Deadlines per part (e.g. Germany: day 1, day 7, one month).

      2 fields
      • partstringrequired
      • duestringrequired
    • deliveryobjectrequired

      electronic (My workspace, email, receipt to confirm) or print (NL without consent, a DE §2a sector).

      2 fields
      • method"electronic" | "print"required
      • why"nl_no_consent" | "de_sector" | "chosen" | "no_consent"required
    • employer_qesbooleanrequired

      NL: sent electronically, it must carry the employer's qualified electronic signature: send a signed copy (signed_document_id).

    • template_idstring | nullrequired

      null: the company's choice for the kind, else the country's built-in.

    • document_idstring | nullrequired

      The document once rendered (HR only until sent).

    • changed_fieldsstring[]required

      Change notices: the fields that changed (values only in the app, in the document).

    • effectivestring | nullrequired

      Change notices: the day the change takes effect.

    • blockedobject | nullrequired

      Why 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
      • onstringrequired
      • whystring (enum)required

        clause: 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 | nullrequired

      Proof of delivery: when it went, how, when the person first opened it and when they confirmed receipt.

      6 fields
      • atstringrequired
      • by"hr" | "auto" | "self"required
      • method"electronic" | "print"required
      • handed_over_onstring | nullrequired
      • opened_atstring | nullrequired
      • acknowledged_atstring | nullrequired
    • discarded_atstring | nullrequired
    • created_atstringrequired
    • variant"renewal" | "reference" | "salary" | "employment"required

      Step 4: renewal (an amendment renewing a fixed-term contract), reference (DE qualified reference), salary or employment (declarations); null: the kind's own document.

    • warningsobject[]required

      What 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"required
      • daysinteger | nullrequired
      • bystring | nullrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
    • decisionobject | nullrequired

      End 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"required
      • new_end_datestring | nullrequired
      • termsstring | nullrequired
    • contract_endstring | nullrequired

      End notices: the contract's end date.

  • approval_pendingbooleanrequired
  • warningsstring[]required

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"
}'
Response
{
  "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_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • status"active" | "retired" | "all"
  • person_idstring

Returns

  • policiesobject[]required
    12 fields
    • idstringrequired
    • template_idstringrequired
    • namestringrequired
    • status"active" | "retired"required
    • audienceobjectrequired

      group_id null: everyone employed; else the members of that saved group.

      1 field
      • group_idstring | nullrequired
    • versionintegerrequired

      The version people are asked to acknowledge now.

    • template_versionintegerrequired
    • newer_template_versioninteger | nullrequired

      A newer published version of its template (publish it to ask everyone again), else null.

    • published_atstringrequired
    • languages"en" | "pt" | "es" | "fr" | "de" | "it"[]required
    • countsobjectrequired

      For the current version, among the people asked today.

      3 fields
      • askedintegerrequired
      • acknowledgedintegerrequired
      • missingintegerrequired
    • for_personobject

      With person_id: whether that person acknowledged the current version (and when), or is late (asked more than 14 days ago).

      2 fields
      • acknowledged_atstring | nullrequired
      • latebooleanrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/documents/policies.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"retired"}'
Response
{
  "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_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • policy_idstringrequired

Returns

  • policyobjectrequired
    12 fields
    • idstringrequired
    • template_idstringrequired
    • namestringrequired
    • status"active" | "retired"required
    • audienceobjectrequired

      group_id null: everyone employed; else the members of that saved group.

      1 field
      • group_idstring | nullrequired
    • versionintegerrequired

      The version people are asked to acknowledge now.

    • template_versionintegerrequired
    • newer_template_versioninteger | nullrequired

      A newer published version of its template (publish it to ask everyone again), else null.

    • published_atstringrequired
    • languages"en" | "pt" | "es" | "fr" | "de" | "it"[]required
    • countsobjectrequired

      For the current version, among the people asked today.

      3 fields
      • askedintegerrequired
      • acknowledgedintegerrequired
      • missingintegerrequired
    • for_personobject

      With person_id: whether that person acknowledged the current version (and when), or is late (asked more than 14 days ago).

      2 fields
      • acknowledged_atstring | nullrequired
      • latebooleanrequired
  • peopleobject[]required
    4 fields
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • acknowledged_atstring | nullrequired
    • last_versioninteger | nullrequired
    • latebooleanrequired
  • versionsobject[]required
    4 fields
    • versionintegerrequired
    • template_versionintegerrequired
    • published_atstringrequired
    • acknowledgedintegerrequired
  • notesobject[]required
    3 fields
    • countrystringrequired
    • textstringrequired

      English; the app translates it.

    • sourceobjectrequired
      2 fields
      • urlstringrequired
      • articlestringrequired
  • changesobject | nullrequired
    4 fields
    • from_versionintegerrequired
    • addedintegerrequired
    • removedintegerrequired
    • segmentsobject[]required
      2 fields
      • op"eq" | "add" | "del"required
      • textstringrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
curl https://api.bizisy.com/v1/documents/policies.get \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"policy_id":"pol1"}'
Response
{
  "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_publish on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • template_idstringrequired
  • group_idstring | null

Returns

  • policyobjectrequired
    12 fields
    • idstringrequired
    • template_idstringrequired
    • namestringrequired
    • status"active" | "retired"required
    • audienceobjectrequired

      group_id null: everyone employed; else the members of that saved group.

      1 field
      • group_idstring | nullrequired
    • versionintegerrequired

      The version people are asked to acknowledge now.

    • template_versionintegerrequired
    • newer_template_versioninteger | nullrequired

      A newer published version of its template (publish it to ask everyone again), else null.

    • published_atstringrequired
    • languages"en" | "pt" | "es" | "fr" | "de" | "it"[]required
    • countsobjectrequired

      For the current version, among the people asked today.

      3 fields
      • askedintegerrequired
      • acknowledgedintegerrequired
      • missingintegerrequired
    • for_personobject

      With person_id: whether that person acknowledged the current version (and when), or is late (asked more than 14 days ago).

      2 fields
      • acknowledged_atstring | nullrequired
      • latebooleanrequired
  • askedintegerrequired
  • new_versionbooleanrequired
  • changesobject | nullrequired
    2 fields
    • addedintegerrequired
    • removedintegerrequired
  • notesobject[]required
    3 fields
    • countrystringrequired
    • textstringrequired

      English; the app translates it.

    • sourceobjectrequired
      2 fields
      • urlstringrequired
      • articlestringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_retire on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • policy_idstringrequired

Returns

  • policyobjectrequired
    12 fields
    • idstringrequired
    • template_idstringrequired
    • namestringrequired
    • status"active" | "retired"required
    • audienceobjectrequired

      group_id null: everyone employed; else the members of that saved group.

      1 field
      • group_idstring | nullrequired
    • versionintegerrequired

      The version people are asked to acknowledge now.

    • template_versionintegerrequired
    • newer_template_versioninteger | nullrequired

      A newer published version of its template (publish it to ask everyone again), else null.

    • published_atstringrequired
    • languages"en" | "pt" | "es" | "fr" | "de" | "it"[]required
    • countsobjectrequired

      For the current version, among the people asked today.

      3 fields
      • askedintegerrequired
      • acknowledgedintegerrequired
      • missingintegerrequired
    • for_personobject

      With person_id: whether that person acknowledged the current version (and when), or is late (asked more than 14 days ago).

      2 fields
      • acknowledged_atstring | nullrequired
      • latebooleanrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_list on HR Assistant
Method
POST with a JSON body, or GET with 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.

  • countrystring

    Pattern ^[A-Z]{2}$.

  • status"draft" | "published" | "archived" | "all"

    Default: drafts and published.

  • source"builtin" | "company"

Returns

  • clausesobject[]required
    13 fields
    • idstringrequired

      A company clause's id, or a starter's (builtin:clause.<country>.<type>).

    • source"builtin" | "company"required

      builtin: Bizisy's starter (copy it to change it); company: your own.

    • typestring (enum)required

      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.

    • category"restrictions" | "start_and_end" | "pay_and_time" | "how_we_work" | "rights"required
    • countrystring (enum)required

      Whose rules it runs (EU: the EU minimum, for any other country).

      One of: PT, ES, FR, DE, IT, NL, EU.

    • namestringrequired
    • languages"en" | "pt" | "es" | "fr" | "de" | "it"[]required
    • status"draft" | "published" | "archived"required
    • versionintegerrequired

      The latest published version (0: never published).

    • has_draftbooleanrequired
    • reviewedboolean | nullrequired

      Starters: a local employment lawyer reviewed the text (false: not yet). null for your own.

    • builtin_fromstring | nullrequired
    • updated_atstring | nullrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_get on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • clause_idstringrequired

Returns

20 fields
  • idstringrequired

    A company clause's id, or a starter's (builtin:clause.<country>.<type>).

  • source"builtin" | "company"required

    builtin: Bizisy's starter (copy it to change it); company: your own.

  • typestring (enum)required

    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.

  • category"restrictions" | "start_and_end" | "pay_and_time" | "how_we_work" | "rights"required
  • countrystring (enum)required

    Whose rules it runs (EU: the EU minimum, for any other country).

    One of: PT, ES, FR, DE, IT, NL, EU.

  • namestringrequired
  • languages"en" | "pt" | "es" | "fr" | "de" | "it"[]required
  • status"draft" | "published" | "archived"required
  • versionintegerrequired

    The latest published version (0: never published).

  • has_draftbooleanrequired
  • reviewedboolean | nullrequired

    Starters: a local employment lawyer reviewed the text (false: not yet). null for your own.

  • builtin_fromstring | nullrequired
  • updated_atstring | nullrequired
  • bodiesobjectrequired
    6 fields
    • enobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • ptobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • esobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • frobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • deobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • itobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

  • defaultsobjectrequired

    Your defaults for its typed fields (HR changes them per document).

  • versionsobject[]required
    2 fields
    • versionintegerrequired
    • published_atstringrequired
  • problemsobject[]required

    Lint warnings in the draft (errors are refused when saving).

    8 fields
    • language"en" | "pt" | "es" | "fr" | "de" | "it"required
    • field"title" | "body"required
    • lineintegerrequired
    • colintegerrequired
    • codestringrequired
    • messagestringrequired
    • severity"error" | "warning"required
    • paramsobject
  • wordingobject[]required

    Wording the rules forbid (pay secrecy, automatic termination, pay fines): blocks refuse publishing.

    6 fields
    • rulestringrequired
    • messagestringrequired

      English with {params}; the app translates it.

    • paramsobject | nullrequired
    • fieldstring | nullrequired

      The typed field it is about.

    • sourceobjectrequired
      2 fields
      • urlstringrequired
      • articlestringrequired
    • confidence"verified" | "medium" | "uncertain"required
  • variantobjectrequired

    The law for its clause type and country: fields, rules, note and sources.

    11 fields
    • countrystring (enum)required

      One of: PT, ES, FR, DE, IT, NL, EU.

    • notestringrequired

      What the law says here (English; the app translates it).

    • sourcesobject[]required
      2 fields
      • urlstringrequired
      • articlestringrequired
    • confidence"verified" | "medium" | "uncertain"required
    • last_reviewedstringrequired
    • effective_fromstringrequired
    • effective_tostring | nullrequired
    • reviewedbooleanrequired
    • fieldsobject[]required
      10 fields
      • namestringrequired
      • type"number" | "text" | "boolean" | "enum" | "list" | "money"required
      • labelstringrequired

        English; the app translates it.

      • unitstring | nullrequired
      • requiredbooleanrequired
      • defaultany
      • valuesobject[] | nullrequired
        2 fields
        • valuestringrequired
        • labelstringrequired
      • minnumber | nullrequired
      • maxnumber | nullrequired
      • hintstring | nullrequired
    • rulesobject[]required
      6 fields
      • idstringrequired
      • severity"block" | "warn"required
      • messagestringrequired
      • fieldstring | nullrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
    • raises_toobject | nullrequired
      2 fields
      • level"none" | "simple" | "advanced" | "qualified" | "wet"required
      • confidence"verified" | "medium" | "uncertain"required
  • documentsintegerrequired

    Documents made with it.

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_create on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • typestring (enum)required

    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.

  • countrystringrequired

    Pattern ^[A-Z]{2}$.

  • namestringrequired

    1–120 characters.

  • bodiesobjectrequired
    6 fields
    • enobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • ptobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • esobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • frobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • deobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • itobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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
  • idstringrequired

    A company clause's id, or a starter's (builtin:clause.<country>.<type>).

  • source"builtin" | "company"required

    builtin: Bizisy's starter (copy it to change it); company: your own.

  • typestring (enum)required

    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.

  • category"restrictions" | "start_and_end" | "pay_and_time" | "how_we_work" | "rights"required
  • countrystring (enum)required

    Whose rules it runs (EU: the EU minimum, for any other country).

    One of: PT, ES, FR, DE, IT, NL, EU.

  • namestringrequired
  • languages"en" | "pt" | "es" | "fr" | "de" | "it"[]required
  • status"draft" | "published" | "archived"required
  • versionintegerrequired

    The latest published version (0: never published).

  • has_draftbooleanrequired
  • reviewedboolean | nullrequired

    Starters: a local employment lawyer reviewed the text (false: not yet). null for your own.

  • builtin_fromstring | nullrequired
  • updated_atstring | nullrequired
  • bodiesobjectrequired
    6 fields
    • enobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • ptobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • esobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • frobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • deobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • itobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

  • defaultsobjectrequired

    Your defaults for its typed fields (HR changes them per document).

  • versionsobject[]required
    2 fields
    • versionintegerrequired
    • published_atstringrequired
  • problemsobject[]required

    Lint warnings in the draft (errors are refused when saving).

    8 fields
    • language"en" | "pt" | "es" | "fr" | "de" | "it"required
    • field"title" | "body"required
    • lineintegerrequired
    • colintegerrequired
    • codestringrequired
    • messagestringrequired
    • severity"error" | "warning"required
    • paramsobject
  • wordingobject[]required

    Wording the rules forbid (pay secrecy, automatic termination, pay fines): blocks refuse publishing.

    6 fields
    • rulestringrequired
    • messagestringrequired

      English with {params}; the app translates it.

    • paramsobject | nullrequired
    • fieldstring | nullrequired

      The typed field it is about.

    • sourceobjectrequired
      2 fields
      • urlstringrequired
      • articlestringrequired
    • confidence"verified" | "medium" | "uncertain"required
  • variantobjectrequired

    The law for its clause type and country: fields, rules, note and sources.

    11 fields
    • countrystring (enum)required

      One of: PT, ES, FR, DE, IT, NL, EU.

    • notestringrequired

      What the law says here (English; the app translates it).

    • sourcesobject[]required
      2 fields
      • urlstringrequired
      • articlestringrequired
    • confidence"verified" | "medium" | "uncertain"required
    • last_reviewedstringrequired
    • effective_fromstringrequired
    • effective_tostring | nullrequired
    • reviewedbooleanrequired
    • fieldsobject[]required
      10 fields
      • namestringrequired
      • type"number" | "text" | "boolean" | "enum" | "list" | "money"required
      • labelstringrequired

        English; the app translates it.

      • unitstring | nullrequired
      • requiredbooleanrequired
      • defaultany
      • valuesobject[] | nullrequired
        2 fields
        • valuestringrequired
        • labelstringrequired
      • minnumber | nullrequired
      • maxnumber | nullrequired
      • hintstring | nullrequired
    • rulesobject[]required
      6 fields
      • idstringrequired
      • severity"block" | "warn"required
      • messagestringrequired
      • fieldstring | nullrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
    • raises_toobject | nullrequired
      2 fields
      • level"none" | "simple" | "advanced" | "qualified" | "wet"required
      • confidence"verified" | "medium" | "uncertain"required
  • documentsintegerrequired

    Documents made with it.

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"
  }
}'
Response
{
  "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_update on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • clause_idstringrequired
  • namestring

    1–120 characters.

  • bodiesobject
    6 fields
    • enobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • ptobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • esobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • frobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • deobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • itobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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
  • idstringrequired

    A company clause's id, or a starter's (builtin:clause.<country>.<type>).

  • source"builtin" | "company"required

    builtin: Bizisy's starter (copy it to change it); company: your own.

  • typestring (enum)required

    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.

  • category"restrictions" | "start_and_end" | "pay_and_time" | "how_we_work" | "rights"required
  • countrystring (enum)required

    Whose rules it runs (EU: the EU minimum, for any other country).

    One of: PT, ES, FR, DE, IT, NL, EU.

  • namestringrequired
  • languages"en" | "pt" | "es" | "fr" | "de" | "it"[]required
  • status"draft" | "published" | "archived"required
  • versionintegerrequired

    The latest published version (0: never published).

  • has_draftbooleanrequired
  • reviewedboolean | nullrequired

    Starters: a local employment lawyer reviewed the text (false: not yet). null for your own.

  • builtin_fromstring | nullrequired
  • updated_atstring | nullrequired
  • bodiesobjectrequired
    6 fields
    • enobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • ptobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • esobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • frobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • deobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • itobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

  • defaultsobjectrequired

    Your defaults for its typed fields (HR changes them per document).

  • versionsobject[]required
    2 fields
    • versionintegerrequired
    • published_atstringrequired
  • problemsobject[]required

    Lint warnings in the draft (errors are refused when saving).

    8 fields
    • language"en" | "pt" | "es" | "fr" | "de" | "it"required
    • field"title" | "body"required
    • lineintegerrequired
    • colintegerrequired
    • codestringrequired
    • messagestringrequired
    • severity"error" | "warning"required
    • paramsobject
  • wordingobject[]required

    Wording the rules forbid (pay secrecy, automatic termination, pay fines): blocks refuse publishing.

    6 fields
    • rulestringrequired
    • messagestringrequired

      English with {params}; the app translates it.

    • paramsobject | nullrequired
    • fieldstring | nullrequired

      The typed field it is about.

    • sourceobjectrequired
      2 fields
      • urlstringrequired
      • articlestringrequired
    • confidence"verified" | "medium" | "uncertain"required
  • variantobjectrequired

    The law for its clause type and country: fields, rules, note and sources.

    11 fields
    • countrystring (enum)required

      One of: PT, ES, FR, DE, IT, NL, EU.

    • notestringrequired

      What the law says here (English; the app translates it).

    • sourcesobject[]required
      2 fields
      • urlstringrequired
      • articlestringrequired
    • confidence"verified" | "medium" | "uncertain"required
    • last_reviewedstringrequired
    • effective_fromstringrequired
    • effective_tostring | nullrequired
    • reviewedbooleanrequired
    • fieldsobject[]required
      10 fields
      • namestringrequired
      • type"number" | "text" | "boolean" | "enum" | "list" | "money"required
      • labelstringrequired

        English; the app translates it.

      • unitstring | nullrequired
      • requiredbooleanrequired
      • defaultany
      • valuesobject[] | nullrequired
        2 fields
        • valuestringrequired
        • labelstringrequired
      • minnumber | nullrequired
      • maxnumber | nullrequired
      • hintstring | nullrequired
    • rulesobject[]required
      6 fields
      • idstringrequired
      • severity"block" | "warn"required
      • messagestringrequired
      • fieldstring | nullrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
    • raises_toobject | nullrequired
      2 fields
      • level"none" | "simple" | "advanced" | "qualified" | "wet"required
      • confidence"verified" | "medium" | "uncertain"required
  • documentsintegerrequired

    Documents made with it.

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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
  }
}'
Response
{
  "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_copy on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • clause_idstringrequired
  • namestring

    1–120 characters.

Returns

20 fields
  • idstringrequired

    A company clause's id, or a starter's (builtin:clause.<country>.<type>).

  • source"builtin" | "company"required

    builtin: Bizisy's starter (copy it to change it); company: your own.

  • typestring (enum)required

    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.

  • category"restrictions" | "start_and_end" | "pay_and_time" | "how_we_work" | "rights"required
  • countrystring (enum)required

    Whose rules it runs (EU: the EU minimum, for any other country).

    One of: PT, ES, FR, DE, IT, NL, EU.

  • namestringrequired
  • languages"en" | "pt" | "es" | "fr" | "de" | "it"[]required
  • status"draft" | "published" | "archived"required
  • versionintegerrequired

    The latest published version (0: never published).

  • has_draftbooleanrequired
  • reviewedboolean | nullrequired

    Starters: a local employment lawyer reviewed the text (false: not yet). null for your own.

  • builtin_fromstring | nullrequired
  • updated_atstring | nullrequired
  • bodiesobjectrequired
    6 fields
    • enobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • ptobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • esobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • frobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • deobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • itobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

  • defaultsobjectrequired

    Your defaults for its typed fields (HR changes them per document).

  • versionsobject[]required
    2 fields
    • versionintegerrequired
    • published_atstringrequired
  • problemsobject[]required

    Lint warnings in the draft (errors are refused when saving).

    8 fields
    • language"en" | "pt" | "es" | "fr" | "de" | "it"required
    • field"title" | "body"required
    • lineintegerrequired
    • colintegerrequired
    • codestringrequired
    • messagestringrequired
    • severity"error" | "warning"required
    • paramsobject
  • wordingobject[]required

    Wording the rules forbid (pay secrecy, automatic termination, pay fines): blocks refuse publishing.

    6 fields
    • rulestringrequired
    • messagestringrequired

      English with {params}; the app translates it.

    • paramsobject | nullrequired
    • fieldstring | nullrequired

      The typed field it is about.

    • sourceobjectrequired
      2 fields
      • urlstringrequired
      • articlestringrequired
    • confidence"verified" | "medium" | "uncertain"required
  • variantobjectrequired

    The law for its clause type and country: fields, rules, note and sources.

    11 fields
    • countrystring (enum)required

      One of: PT, ES, FR, DE, IT, NL, EU.

    • notestringrequired

      What the law says here (English; the app translates it).

    • sourcesobject[]required
      2 fields
      • urlstringrequired
      • articlestringrequired
    • confidence"verified" | "medium" | "uncertain"required
    • last_reviewedstringrequired
    • effective_fromstringrequired
    • effective_tostring | nullrequired
    • reviewedbooleanrequired
    • fieldsobject[]required
      10 fields
      • namestringrequired
      • type"number" | "text" | "boolean" | "enum" | "list" | "money"required
      • labelstringrequired

        English; the app translates it.

      • unitstring | nullrequired
      • requiredbooleanrequired
      • defaultany
      • valuesobject[] | nullrequired
        2 fields
        • valuestringrequired
        • labelstringrequired
      • minnumber | nullrequired
      • maxnumber | nullrequired
      • hintstring | nullrequired
    • rulesobject[]required
      6 fields
      • idstringrequired
      • severity"block" | "warn"required
      • messagestringrequired
      • fieldstring | nullrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
    • raises_toobject | nullrequired
      2 fields
      • level"none" | "simple" | "advanced" | "qualified" | "wet"required
      • confidence"verified" | "medium" | "uncertain"required
  • documentsintegerrequired

    Documents made with it.

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_archive on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • clause_idstringrequired
  • archivedboolean

Returns

20 fields
  • idstringrequired

    A company clause's id, or a starter's (builtin:clause.<country>.<type>).

  • source"builtin" | "company"required

    builtin: Bizisy's starter (copy it to change it); company: your own.

  • typestring (enum)required

    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.

  • category"restrictions" | "start_and_end" | "pay_and_time" | "how_we_work" | "rights"required
  • countrystring (enum)required

    Whose rules it runs (EU: the EU minimum, for any other country).

    One of: PT, ES, FR, DE, IT, NL, EU.

  • namestringrequired
  • languages"en" | "pt" | "es" | "fr" | "de" | "it"[]required
  • status"draft" | "published" | "archived"required
  • versionintegerrequired

    The latest published version (0: never published).

  • has_draftbooleanrequired
  • reviewedboolean | nullrequired

    Starters: a local employment lawyer reviewed the text (false: not yet). null for your own.

  • builtin_fromstring | nullrequired
  • updated_atstring | nullrequired
  • bodiesobjectrequired
    6 fields
    • enobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • ptobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • esobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • frobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • deobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • itobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

  • defaultsobjectrequired

    Your defaults for its typed fields (HR changes them per document).

  • versionsobject[]required
    2 fields
    • versionintegerrequired
    • published_atstringrequired
  • problemsobject[]required

    Lint warnings in the draft (errors are refused when saving).

    8 fields
    • language"en" | "pt" | "es" | "fr" | "de" | "it"required
    • field"title" | "body"required
    • lineintegerrequired
    • colintegerrequired
    • codestringrequired
    • messagestringrequired
    • severity"error" | "warning"required
    • paramsobject
  • wordingobject[]required

    Wording the rules forbid (pay secrecy, automatic termination, pay fines): blocks refuse publishing.

    6 fields
    • rulestringrequired
    • messagestringrequired

      English with {params}; the app translates it.

    • paramsobject | nullrequired
    • fieldstring | nullrequired

      The typed field it is about.

    • sourceobjectrequired
      2 fields
      • urlstringrequired
      • articlestringrequired
    • confidence"verified" | "medium" | "uncertain"required
  • variantobjectrequired

    The law for its clause type and country: fields, rules, note and sources.

    11 fields
    • countrystring (enum)required

      One of: PT, ES, FR, DE, IT, NL, EU.

    • notestringrequired

      What the law says here (English; the app translates it).

    • sourcesobject[]required
      2 fields
      • urlstringrequired
      • articlestringrequired
    • confidence"verified" | "medium" | "uncertain"required
    • last_reviewedstringrequired
    • effective_fromstringrequired
    • effective_tostring | nullrequired
    • reviewedbooleanrequired
    • fieldsobject[]required
      10 fields
      • namestringrequired
      • type"number" | "text" | "boolean" | "enum" | "list" | "money"required
      • labelstringrequired

        English; the app translates it.

      • unitstring | nullrequired
      • requiredbooleanrequired
      • defaultany
      • valuesobject[] | nullrequired
        2 fields
        • valuestringrequired
        • labelstringrequired
      • minnumber | nullrequired
      • maxnumber | nullrequired
      • hintstring | nullrequired
    • rulesobject[]required
      6 fields
      • idstringrequired
      • severity"block" | "warn"required
      • messagestringrequired
      • fieldstring | nullrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
    • raises_toobject | nullrequired
      2 fields
      • level"none" | "simple" | "advanced" | "qualified" | "wet"required
      • confidence"verified" | "medium" | "uncertain"required
  • documentsintegerrequired

    Documents made with it.

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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}'
Response
{
  "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_publish on HR Assistant
Preview
?dry_run=true runs every check and saves nothing
Retries
An Idempotency-Key replays the first result

Input

  • clause_idstringrequired

Returns

21 fields
  • idstringrequired

    A company clause's id, or a starter's (builtin:clause.<country>.<type>).

  • source"builtin" | "company"required

    builtin: Bizisy's starter (copy it to change it); company: your own.

  • typestring (enum)required

    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.

  • category"restrictions" | "start_and_end" | "pay_and_time" | "how_we_work" | "rights"required
  • countrystring (enum)required

    Whose rules it runs (EU: the EU minimum, for any other country).

    One of: PT, ES, FR, DE, IT, NL, EU.

  • namestringrequired
  • languages"en" | "pt" | "es" | "fr" | "de" | "it"[]required
  • status"draft" | "published" | "archived"required
  • versionintegerrequired

    The latest published version (0: never published).

  • has_draftbooleanrequired
  • reviewedboolean | nullrequired

    Starters: a local employment lawyer reviewed the text (false: not yet). null for your own.

  • builtin_fromstring | nullrequired
  • updated_atstring | nullrequired
  • bodiesobjectrequired
    6 fields
    • enobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • ptobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • esobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • frobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • deobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

    • itobject
      2 fields
      • titlestringrequired

        The clause's heading in the document.

        1–120 characters.

      • bodystringrequired

        Markdown-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.

  • defaultsobjectrequired

    Your defaults for its typed fields (HR changes them per document).

  • versionsobject[]required
    2 fields
    • versionintegerrequired
    • published_atstringrequired
  • problemsobject[]required

    Lint warnings in the draft (errors are refused when saving).

    8 fields
    • language"en" | "pt" | "es" | "fr" | "de" | "it"required
    • field"title" | "body"required
    • lineintegerrequired
    • colintegerrequired
    • codestringrequired
    • messagestringrequired
    • severity"error" | "warning"required
    • paramsobject
  • wordingobject[]required

    Wording the rules forbid (pay secrecy, automatic termination, pay fines): blocks refuse publishing.

    6 fields
    • rulestringrequired
    • messagestringrequired

      English with {params}; the app translates it.

    • paramsobject | nullrequired
    • fieldstring | nullrequired

      The typed field it is about.

    • sourceobjectrequired
      2 fields
      • urlstringrequired
      • articlestringrequired
    • confidence"verified" | "medium" | "uncertain"required
  • variantobjectrequired

    The law for its clause type and country: fields, rules, note and sources.

    11 fields
    • countrystring (enum)required

      One of: PT, ES, FR, DE, IT, NL, EU.

    • notestringrequired

      What the law says here (English; the app translates it).

    • sourcesobject[]required
      2 fields
      • urlstringrequired
      • articlestringrequired
    • confidence"verified" | "medium" | "uncertain"required
    • last_reviewedstringrequired
    • effective_fromstringrequired
    • effective_tostring | nullrequired
    • reviewedbooleanrequired
    • fieldsobject[]required
      10 fields
      • namestringrequired
      • type"number" | "text" | "boolean" | "enum" | "list" | "money"required
      • labelstringrequired

        English; the app translates it.

      • unitstring | nullrequired
      • requiredbooleanrequired
      • defaultany
      • valuesobject[] | nullrequired
        2 fields
        • valuestringrequired
        • labelstringrequired
      • minnumber | nullrequired
      • maxnumber | nullrequired
      • hintstring | nullrequired
    • rulesobject[]required
      6 fields
      • idstringrequired
      • severity"block" | "warn"required
      • messagestringrequired
      • fieldstring | nullrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
    • raises_toobject | nullrequired
      2 fields
      • level"none" | "simple" | "advanced" | "qualified" | "wet"required
      • confidence"verified" | "medium" | "uncertain"required
  • documentsintegerrequired

    Documents made with it.

  • published_versionintegerrequired

Errors

validation_failed unauthenticated forbidden not_found conflict module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_preview on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • clause_idstring
  • versioninteger

    At 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.

  • countrystring

    Pattern ^[A-Z]{2}$.

  • titlestring

    Up to 120 characters.

  • bodystring

    Up 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.

  • fieldsobject
  • contextobject
    5 fields
    • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"
    • term_daysinteger

      A fixed-term contract's length in days.

      From 1 to 3650.

    • is_minorboolean
    • part_timeboolean
    • company_sizeinteger

      From 1 to 1000000.

Returns

  • htmlstringrequired
  • language"en" | "pt" | "es" | "fr" | "de" | "it"required
  • problemsobject[]required
    8 fields
    • language"en" | "pt" | "es" | "fr" | "de" | "it"required
    • field"title" | "body"required
    • lineintegerrequired
    • colintegerrequired
    • codestringrequired
    • messagestringrequired
    • severity"error" | "warning"required
    • paramsobject
  • checkobjectrequired
    7 fields
    • okbooleanrequired

      No block: the clause may go in the document.

    • countrystring (enum)required

      Whose 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[]required

      The law Bizisy treats as settled is broken: the document is refused with it.

      6 fields
      • rulestringrequired
      • messagestringrequired

        English with {params}; the app translates it.

      • paramsobject | nullrequired
      • fieldstring | nullrequired

        The typed field it is about.

      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
    • warnsobject[]required

      Less certain rules and reminders: the document is made, check with your lawyer.

      6 fields
      • rulestringrequired
      • messagestringrequired

        English with {params}; the app translates it.

      • paramsobject | nullrequired
      • fieldstring | nullrequired

        The typed field it is about.

      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
    • raises_toobject | nullrequired

      The signature level the clause needs (e.g. a German non-compete: qualified or by hand).

      3 fields
      • level"none" | "simple" | "advanced" | "qualified" | "wet"required
      • confidence"verified" | "medium" | "uncertain"required
      • sourceobject | nullrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
    • tasksobject[]required

      To do once signed (Italy: file the smart-working agreement within 5 days).

      4 fields
      • idstringrequired
      • labelstringrequired
      • days_after_startintegerrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
    • fieldsobjectrequired

      The fields as checked (defaults filled in).

  • variantobjectrequired
    11 fields
    • countrystring (enum)required

      One of: PT, ES, FR, DE, IT, NL, EU.

    • notestringrequired

      What the law says here (English; the app translates it).

    • sourcesobject[]required
      2 fields
      • urlstringrequired
      • articlestringrequired
    • confidence"verified" | "medium" | "uncertain"required
    • last_reviewedstringrequired
    • effective_fromstringrequired
    • effective_tostring | nullrequired
    • reviewedbooleanrequired
    • fieldsobject[]required
      10 fields
      • namestringrequired
      • type"number" | "text" | "boolean" | "enum" | "list" | "money"required
      • labelstringrequired

        English; the app translates it.

      • unitstring | nullrequired
      • requiredbooleanrequired
      • defaultany
      • valuesobject[] | nullrequired
        2 fields
        • valuestringrequired
        • labelstringrequired
      • minnumber | nullrequired
      • maxnumber | nullrequired
      • hintstring | nullrequired
    • rulesobject[]required
      6 fields
      • idstringrequired
      • severity"block" | "warn"required
      • messagestringrequired
      • fieldstring | nullrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
    • raises_toobject | nullrequired
      2 fields
      • level"none" | "simple" | "advanced" | "qualified" | "wet"required
      • confidence"verified" | "medium" | "uncertain"required

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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
  }
}'
Response
{
  "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_check on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • typestring (enum)required

    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.

  • countrystringrequired

    Pattern ^[A-Z]{2}$.

  • fieldsobject
  • contextobject
    5 fields
    • contract_type"permanent" | "fixed_term" | "temporary" | "internship" | "freelance"
    • term_daysinteger

      A fixed-term contract's length in days.

      From 1 to 3650.

    • is_minorboolean
    • part_timeboolean
    • company_sizeinteger

      From 1 to 1000000.

  • textstring

    Up to 8000 characters.

Returns

8 fields
  • okbooleanrequired

    No block: the clause may go in the document.

  • countrystring (enum)required

    Whose 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[]required

    The law Bizisy treats as settled is broken: the document is refused with it.

    6 fields
    • rulestringrequired
    • messagestringrequired

      English with {params}; the app translates it.

    • paramsobject | nullrequired
    • fieldstring | nullrequired

      The typed field it is about.

    • sourceobjectrequired
      2 fields
      • urlstringrequired
      • articlestringrequired
    • confidence"verified" | "medium" | "uncertain"required
  • warnsobject[]required

    Less certain rules and reminders: the document is made, check with your lawyer.

    6 fields
    • rulestringrequired
    • messagestringrequired

      English with {params}; the app translates it.

    • paramsobject | nullrequired
    • fieldstring | nullrequired

      The typed field it is about.

    • sourceobjectrequired
      2 fields
      • urlstringrequired
      • articlestringrequired
    • confidence"verified" | "medium" | "uncertain"required
  • raises_toobject | nullrequired

    The signature level the clause needs (e.g. a German non-compete: qualified or by hand).

    3 fields
    • level"none" | "simple" | "advanced" | "qualified" | "wet"required
    • confidence"verified" | "medium" | "uncertain"required
    • sourceobject | nullrequired
      2 fields
      • urlstringrequired
      • articlestringrequired
  • tasksobject[]required

    To do once signed (Italy: file the smart-working agreement within 5 days).

    4 fields
    • idstringrequired
    • labelstringrequired
    • days_after_startintegerrequired
    • sourceobjectrequired
      2 fields
      • urlstringrequired
      • articlestringrequired
  • fieldsobjectrequired

    The fields as checked (defaults filled in).

  • variantobjectrequired
    11 fields
    • countrystring (enum)required

      One of: PT, ES, FR, DE, IT, NL, EU.

    • notestringrequired

      What the law says here (English; the app translates it).

    • sourcesobject[]required
      2 fields
      • urlstringrequired
      • articlestringrequired
    • confidence"verified" | "medium" | "uncertain"required
    • last_reviewedstringrequired
    • effective_fromstringrequired
    • effective_tostring | nullrequired
    • reviewedbooleanrequired
    • fieldsobject[]required
      10 fields
      • namestringrequired
      • type"number" | "text" | "boolean" | "enum" | "list" | "money"required
      • labelstringrequired

        English; the app translates it.

      • unitstring | nullrequired
      • requiredbooleanrequired
      • defaultany
      • valuesobject[] | nullrequired
        2 fields
        • valuestringrequired
        • labelstringrequired
      • minnumber | nullrequired
      • maxnumber | nullrequired
      • hintstring | nullrequired
    • rulesobject[]required
      6 fields
      • idstringrequired
      • severity"block" | "warn"required
      • messagestringrequired
      • fieldstring | nullrequired
      • sourceobjectrequired
        2 fields
        • urlstringrequired
        • articlestringrequired
      • confidence"verified" | "medium" | "uncertain"required
    • raises_toobject | nullrequired
      2 fields
      • level"none" | "simple" | "advanced" | "qualified" | "wet"required
      • confidence"verified" | "medium" | "uncertain"required

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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é…"
}'
Response
{
  "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_list on HR Assistant
Method
POST with a JSON body, or GET with the input as query parameters

Input

  • status"to_review" | "waiting" | "signed" | "not_signed" | "uploaded" | "missing"
  • typestring

    Up to 40 characters.

  • countrystring

    Pattern ^[A-Z]{2}$.

  • ending_within_daysinteger

    From 0 to 366.

  • qstring

    Up to 100 characters.

  • person_idstring

Returns

  • contractsobject[]required
    19 fields
    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • status"to_review" | "waiting" | "signed" | "not_signed" | "uploaded" | "missing"required

      to_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"required

      Employed today, or starting later.

    • typestring | nullrequired

      The contract type org records (permanent, fixed_term, temporary, internship, freelance); null when not recorded.

    • part_timebooleanrequired
    • countrystring | nullrequired

      The country whose law applies (their employer's, else their location's).

    • titlestring | nullrequired
    • startstring | nullrequired

      The first day of their current employment.

    • endstring | nullrequired

      The contract end date (fixed-term).

    • ends_in_daysinteger | nullrequired
    • documentobject | nullrequired

      Their current contract document (the newest); null when missing.

      9 fields
      • idstringrequired
      • titlestringrequired
      • categorystringrequired
      • source"template" | "upload"required

        template: made from a document template; upload: a file HR uploaded.

      • kindstring (enum)required

        The 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 | nullrequired
      • versioninteger | nullrequired
      • languagestring | nullrequired
      • created_atstringrequired
    • prepared_idstring | nullrequired

      to_review: the prepared document to review and send.

    • signatureobject | nullrequired
      9 fields
      • idstringrequired
      • statusstring (enum)required

        One of: queued, sending, ongoing, done, declined, expired, canceled, failed.

      • level"simple" | "advanced" | "qualified"required
      • signedintegerrequired
      • totalintegerrequired
      • nextobject | nullrequired

        Who signs next (open requests only).

        3 fields
        • role"person" | "manager" | "me" | "other"required

          person: the person the document is about; manager: their manager; me: the HR member who sent it (the employer); other.

        • namestring | nullrequired

          null through API keys and AI assistants, and once erased.

        • youbooleanrequired

          It is your turn to sign.

      • sent_atstring | nullrequired
      • completed_atstring | nullrequired
      • expires_onstringrequired
    • signed_atstring | nullrequired
    • signed_document_idstring | nullrequired
    • amendmentsobjectrequired
      3 fields
      • countintegerrequired

        Amendments and addenda on file.

      • to_reviewstring | nullrequired

        An amendment Bizisy prepared waiting for HR: its prepared id.

      • documentsobject[]required

        The amendments and addenda on file, newest first.

        9 fields
        • idstringrequired
        • titlestringrequired
        • categorystringrequired
        • source"template" | "upload"required

          template: made from a document template; upload: a file HR uploaded.

        • kindstring (enum)required

          The 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 | nullrequired
        • versioninteger | nullrequired
        • languagestring | nullrequired
        • created_atstringrequired
    • end_noticeobject | nullrequired

      A 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_idstringrequired
      • decidedbooleanrequired
    • versionsintegerrequired

      Contract documents on file for them (the current one and earlier ones).

    • earlierobject[]required

      Their earlier contract documents, newest first.

      9 fields
      • idstringrequired
      • titlestringrequired
      • categorystringrequired
      • source"template" | "upload"required

        template: made from a document template; upload: a file HR uploaded.

      • kindstring (enum)required

        The 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 | nullrequired
      • versioninteger | nullrequired
      • languagestring | nullrequired
      • created_atstringrequired
  • countsobjectrequired
    7 fields
    • allintegerrequired
    • to_reviewintegerrequired
    • waitingintegerrequired
    • signedintegerrequired
    • missingintegerrequired
    • ending_soonintegerrequired
    • amendments_to_reviewintegerrequired
  • typesstring[]required

    The contract types in use (for a filter).

  • countriesstring[]required

    The countries in use (for a filter).

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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"}'
Response
{
  "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_list on HR Assistant
Method
POST with a JSON body, or GET with 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[]required
    14 fields
    • idstringrequired

      The prepared document's id (prep_…) when Bizisy prepared it, else the document's.

    • personobjectrequired
      2 fields
      • idstringrequired
      • namestringrequired
    • kindstring (enum)required

      statement, 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"required
    • status"to_review" | "requested" | "waiting" | "signed" | "sent" | "accepted"required

      to_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"required
    • reasonstring (enum)required

      Why 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 | nullrequired
    • document_idstring | nullrequired
    • due_onstring | nullrequired

      The legal deadline to give it (prepared ones).

    • overduebooleanrequired
    • datestringrequired

      When it was sent, signed or made (YYYY-MM-DD).

    • signatureobject | nullrequired
      9 fields
      • idstringrequired
      • statusstring (enum)required

        One of: queued, sending, ongoing, done, declined, expired, canceled, failed.

      • level"simple" | "advanced" | "qualified"required
      • signedintegerrequired
      • totalintegerrequired
      • nextobject | nullrequired

        Who signs next (open requests only).

        3 fields
        • role"person" | "manager" | "me" | "other"required

          person: the person the document is about; manager: their manager; me: the HR member who sent it (the employer); other.

        • namestring | nullrequired

          null through API keys and AI assistants, and once erased.

        • youbooleanrequired

          It is your turn to sign.

      • sent_atstring | nullrequired
      • completed_atstring | nullrequired
      • expires_onstringrequired
    • decidedboolean | nullrequired

      End-of-term notices: whether HR decided the contract (null for others).

  • countsobjectrequired
    5 fields
    • allintegerrequired
    • to_reviewintegerrequired
    • requestedintegerrequired
    • waitingintegerrequired
    • sentintegerrequired

Errors

validation_failed unauthenticated forbidden not_found module_disabled rate_limited internal

curl
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"}'
Response
{
  "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.

Developer docs