API reference

My documents

A person's own documents (Me keys).

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

List my documents#

POST/v1/documents/me.listRead

Lists documents shared with you, newest first. scope mine (default): your own documents (shared with you by HR, and the ones you added "From me"); company: company documents for you (handbook, policies…); person_id: documents of someone who reports to you that HR shared with their managers. Also says whether you can add your own documents this month (self_upload).

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

Input

scope"mine" | "company"
person_idstring

Returns

documentsobject[]required
14 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
- visibility"hr" | "hr_person" | "hr_person_manager" | "everyone" | "managers" | "hr"required
- 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.
- status"pending" | "ready"required
- created_atstringrequired
- updated_atstringrequired
categoriesstring[]required
self_uploadobject | nullrequired
null when your login is not linked to a person.
4 fields
- enabledbooleanrequired
  Your company lets people add their own documents ("From me").
- files_leftintegerrequired
  Files you can still add this month.
- bytes_leftintegerrequired
  Bytes you can still add this month.
- max_file_bytesintegerrequired
  The largest file allowed.

Errors

validation_failed unauthenticated forbidden not_found rate_limited internal

curl

curl https://api.bizisy.com/v1/documents/me.list \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope":"company"}'

Node

const res = await fetch('https://api.bizisy.com/v1/documents/me.list', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "scope": "company"
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);

Python

import os
import requests

res = requests.post(
    "https://api.bizisy.com/v1/documents/me.list",
    headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
    json={
        "scope": "company",
    },
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"])

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"
      },
      {
        "id": "d4",
        "title": "Contract 2026",
        "category": "Contract",
        "subject": {
          "kind": "person",
          "person": {
            "id": "p1",
            "name": "Ana Ferreira"
          }
        },
        "visibility": "hr_person",
        "uploaded_by": "self",
        "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"
      }
    ],
    "categories": [
      "Contract",
      "Addendum",
      "Certificate",
      "ID",
      "Policy",
      "Handbook",
      "Other"
    ],
    "self_upload": {
      "enabled": true,
      "files_left": 19,
      "bytes_left": 99000000,
      "max_file_bytes": 25000000
    }
  }
}

Download a document#

POST/v1/documents/me.downloadWrite

Returns a short-lived link (5 minutes) that downloads a document shared with you as a file. Downloading a person document is recorded in Activity. The link is never stored; ask again for a new one.

Who can call it: Me key anyone
MCP tool: documents_me_download on My Workplace
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

7 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

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl

curl https://api.bizisy.com/v1/documents/me.download \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"document_id":"d1"}'

Node

const res = await fetch('https://api.bizisy.com/v1/documents/me.download', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "document_id": "d1"
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);

Python

import os, uuid
import requests

res = requests.post(
    "https://api.bizisy.com/v1/documents/me.download",
    headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "document_id": "d1",
    },
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"])

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"
  }
}

Add my own document#

POST/v1/documents/me.upload.startWrite

Adds a document to your "From me" folder in two calls and one upload (like documents_upload_start): this call with the category, optional title and expiry date and the file's name, size, content_type and sha256; PUT the bytes to the signed URL within 15 minutes with exactly the returned headers; then documents_me_upload_finish. Only you and your HR team (owners, admins, HR) see it; HR is emailed when it arrives. Limits: the largest file, and per month a number of files and MB set by your company (see documents_me_list self_upload).

Who can call it: Me key anyone
MCP tool: documents_me_upload_start on My Workplace
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

categorystring
Default Other.
1–40 characters.
titlestring
Up to 200 characters.
expires_onstring | null
Pattern ^\d{4}-\d{2}-\d{2}$.
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
14 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
- visibility"hr" | "hr_person" | "hr_person_manager" | "everyone" | "managers" | "hr"required
- 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.
- status"pending" | "ready"required
- created_atstringrequired
- updated_atstringrequired
uploadobject | nullrequired
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 rate_limited internal

curl

curl https://api.bizisy.com/v1/documents/me.upload.start \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "category": "Certificate",
  "title": "Medical certificate",
  "expires_on": "2026-12-31",
  "file": {
    "name": "Contract 2026.pdf",
    "size": 182000,
    "content_type": "application/pdf",
    "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }
}'

Node

const res = await fetch('https://api.bizisy.com/v1/documents/me.upload.start', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "category": "Certificate",
    "title": "Medical certificate",
    "expires_on": "2026-12-31",
    "file": {
      "name": "Contract 2026.pdf",
      "size": 182000,
      "content_type": "application/pdf",
      "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
    }
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);

Python

import os, uuid
import requests

res = requests.post(
    "https://api.bizisy.com/v1/documents/me.upload.start",
    headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "category": "Certificate",
        "title": "Medical certificate",
        "expires_on": "2026-12-31",
        "file": {
            "name": "Contract 2026.pdf",
            "size": 182000,
            "content_type": "application/pdf",
            "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        },
    },
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"])

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"
    },
    "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 adding my document#

POST/v1/documents/me.upload.finishWrite

Finishes your "From me" upload after the bytes were uploaded: Bizisy checks the file (size, SHA-256, type from the bytes) and your monthly limits, then it appears in My documents and your HR team is emailed (the email never includes the file name). Finishing twice returns the document.

Who can call it: Me key anyone
MCP tool: documents_me_upload_finish on My Workplace
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

14 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
visibility"hr" | "hr_person" | "hr_person_manager" | "everyone" | "managers" | "hr"required
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.
status"pending" | "ready"required
created_atstringrequired
updated_atstringrequired

Errors

validation_failed unauthenticated forbidden not_found conflict rate_limited internal

curl

curl https://api.bizisy.com/v1/documents/me.upload.finish \
  -H "Authorization: Bearer $BIZISY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"document_id":"d1"}'

Node

const res = await fetch('https://api.bizisy.com/v1/documents/me.upload.finish', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    "document_id": "d1"
  }),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);

Python

import os, uuid
import requests

res = requests.post(
    "https://api.bizisy.com/v1/documents/me.upload.finish",
    headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "document_id": "d1",
    },
)
body = res.json()
if not res.ok:
    raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"])

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"
  }
}

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