API reference
Custom fields
Fields of your own on every person, each with a visibility tier.
3 actions · base URL https://api.bizisy.com/v1 · generated from the same definitions as the API.
List custom fields#
POST/v1/org/fields.listRead
Lists the organization's custom fields (key, label, type, options for select, columns for table, tier, target, effective_dated, archived). target says where values live: person (org_people_get → custom; set with org_people_update_profile or org_people_hire), job (each job row → job.custom and history[].custom; effective-dated: set with org_people_change_job from a date, org_people_correct_job for one row, org_people_hire for the first job), unit (a team: org_units_list → custom; set with org_units_update) or position (org_positions_get → custom; set with org_positions_update). Types: text, number, date (YYYY-MM-DD), select (one of options), boolean, file (person only: uploaded), person (a person id; returned with person {id, name}), table (rows: [{ <column key>: value }]). Tier decides who sees a field: public, job (the person, their managers and HR) or private (the person and HR; team and position private fields: owners, admins and HR signed in to Bizisy). target filters.
- Who can call it
- Manage key any Manage role
Me key anyone - MCP tool
org_fields_liston My Workplace, HR Assistant- Method
POSTwith a JSON body, orGETwith the input as query parameters
Input
include_archivedbooleantarget"person" | "job" | "unit" | "position"
Returns
An array of objects with 13 fields
An array of objects:
idstringrequiredkeystringrequiredlabelstringrequiredtypestring (enum)requiredOne of:
text,number,date,select,boolean,file,person,table.optionsstring[]requiredtier"public" | "job" | "private"requiredarchivedbooleanrequiredpositionintegerrequiredfileobject | nullrequiredType file only; null for other types.
3 fields
kinds"pdf" | "image" | "office"[]requiredpdf (PDF), image (PNG, JPEG, WebP, HEIC), office (DOCX, XLSX, ODT, ODS).
max_mbinteger | nullrequiredThe field's largest file in MB; null = the company's limit. The smaller of the two applies.
self_uploadbooleanrequiredPeople upload their own file in Bizisy Me (it counts toward their monthly self-upload limit).
target"person" | "job" | "unit" | "position"requiredWhere values live: person (the profile), job (each job row: effective-dated), unit (a team) or position (an open position).
effective_datedbooleanrequiredValues follow the job timeline (job fields): a change from a date keeps the earlier value in history.
columnsobject[] | nullrequiredType table only: its columns; null for other types.
4 fields
keystringrequiredlabelstringrequiredtype"text" | "number" | "date" | "select" | "boolean"requiredoptionsstring[]required
analyticsbooleanrequiredUsable as a dimension in people analytics (aggregated only, groups under the minimum hidden; select and yes/no fields on people or jobs).
Errors
validation_failed unauthenticated forbidden not_found rate_limited internal
curl https://api.bizisy.com/v1/org/fields.list \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"include_archived":true}'const res = await fetch('https://api.bizisy.com/v1/org/fields.list', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"include_archived": true
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/fields.list",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}"},
json={
"include_archived": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": [
{
"id": "f1",
"key": "t_shirt_size",
"label": "T-shirt size",
"type": "select",
"options": [
"S",
"M",
"L"
],
"tier": "public",
"archived": false,
"position": 1,
"file": null,
"target": "person",
"effective_dated": false,
"columns": null,
"analytics": false
},
{
"id": "f2",
"key": "driving_licence",
"label": "Driving licence",
"type": "file",
"options": [],
"tier": "private",
"archived": false,
"position": 2,
"file": {
"kinds": [
"pdf",
"image"
],
"max_mb": 10,
"self_upload": true
},
"target": "person",
"effective_dated": false,
"columns": null,
"analytics": false
},
{
"id": "f3",
"key": "shift_pattern",
"label": "Shift pattern",
"type": "select",
"options": [
"Day",
"Night"
],
"tier": "job",
"archived": false,
"position": 3,
"file": null,
"target": "job",
"effective_dated": true,
"columns": null,
"analytics": false
},
{
"id": "f4",
"key": "certifications",
"label": "Certifications",
"type": "table",
"options": [],
"tier": "job",
"archived": false,
"position": 4,
"file": null,
"target": "person",
"effective_dated": false,
"columns": [
{
"key": "name",
"label": "Name",
"type": "text",
"options": []
},
{
"key": "expires",
"label": "Expires",
"type": "date",
"options": []
}
],
"analytics": false
},
{
"id": "f5",
"key": "cost_centre",
"label": "Cost centre",
"type": "text",
"options": [],
"tier": "public",
"archived": false,
"position": 5,
"file": null,
"target": "unit",
"effective_dated": false,
"columns": null,
"analytics": false
}
]
}Add a custom field#
POST/v1/org/fields.createWrite
Adds a custom field. target: person (default), job (values follow the job timeline: a job change copies them forward, history keeps each row's value — e.g. shift pattern, collective agreement category), unit (a team, e.g. cost centre) or position (an open position). label (shown in the app), type (text, number, date, select, boolean, file, person, table), options (2–50, select only), columns (table only: 1–10 of { label, type: text, number, date, select or boolean, options for select, key optional }), tier — person: public (everyone in the org), job (the person, their managers and HR) or private (the person and HR; default); job: job only (the person, their managers and HR, like every job detail); unit: public (everyone; default) or private (owners, admins, HR and roles that manage the structure, signed in to Bizisy: not API keys or AI apps); position: public (whoever sees the position; default) or private (owners, admins and HR with the whole position, signed in to Bizisy: not API keys or AI apps). key defaults to the label in snake_case and never changes; keys are unique across targets. person fields hold a colleague (a person id). File fields are person fields only; they hold one file per person (a document: it also shows in the person's Documents, from the field) and take file: { kinds (pdf, image, office; default all), max_mb (1–100 or null for the company's largest-file limit; the smaller applies), self_upload (default false: people upload their own in Bizisy Me, counted toward their monthly self-upload limit) }; their files follow the field's tier. At most 30 active fields per target.
- Who can call it
- Manage key owner admin hr
- MCP tool
org_fields_createon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
labelstringrequired1–60 characters.
typestring (enum)requiredOne of:
text,number,date,select,boolean,file,person,table.optionsstring[]1–80 characters. 2–50 items.
tier"public" | "job" | "private"target"person" | "job" | "unit" | "position"keystringPattern
^[a-z][a-z0-9_]{0,39}$.fileobject3 fields
kinds"pdf" | "image" | "office"[]1–10 items.
max_mbinteger | nullFrom 1 to 100.
self_uploadboolean
columnsobject[]1–10 items.
4 fields
keystringDefaults to the label in snake_case; never changes.
Pattern
^[a-z][a-z0-9_]{0,39}$.labelstringrequired1–60 characters.
type"text" | "number" | "date" | "select" | "boolean"requiredoptionsstring[]select columns only: 2–50 options.
1–80 characters. 2–50 items.
analyticsbooleanUse in people analytics (aggregated only): the field becomes a dimension of Reports → People analytics, groups under the minimum size hidden, never listed per person and never given to API keys or AI apps. Select or yes/no fields on people or jobs only; refused for special-category data (GDPR Art. 9: health, ethnicity, religion, sexual orientation, disability, trade union, political opinions, biometric or genetic data).
Returns
13 fields
idstringrequiredkeystringrequiredlabelstringrequiredtypestring (enum)requiredOne of:
text,number,date,select,boolean,file,person,table.optionsstring[]requiredtier"public" | "job" | "private"requiredarchivedbooleanrequiredpositionintegerrequiredfileobject | nullrequiredType file only; null for other types.
3 fields
kinds"pdf" | "image" | "office"[]requiredpdf (PDF), image (PNG, JPEG, WebP, HEIC), office (DOCX, XLSX, ODT, ODS).
max_mbinteger | nullrequiredThe field's largest file in MB; null = the company's limit. The smaller of the two applies.
self_uploadbooleanrequiredPeople upload their own file in Bizisy Me (it counts toward their monthly self-upload limit).
target"person" | "job" | "unit" | "position"requiredWhere values live: person (the profile), job (each job row: effective-dated), unit (a team) or position (an open position).
effective_datedbooleanrequiredValues follow the job timeline (job fields): a change from a date keeps the earlier value in history.
columnsobject[] | nullrequiredType table only: its columns; null for other types.
4 fields
keystringrequiredlabelstringrequiredtype"text" | "number" | "date" | "select" | "boolean"requiredoptionsstring[]required
analyticsbooleanrequiredUsable as a dimension in people analytics (aggregated only, groups under the minimum hidden; select and yes/no fields on people or jobs).
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/fields.create \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"label": "Driving licence",
"type": "file",
"file": {
"kinds": [
"pdf",
"image"
],
"max_mb": 10,
"self_upload": true
}
}'const res = await fetch('https://api.bizisy.com/v1/org/fields.create', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"label": "Driving licence",
"type": "file",
"file": {
"kinds": [
"pdf",
"image"
],
"max_mb": 10,
"self_upload": true
}
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/fields.create",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"label": "Driving licence",
"type": "file",
"file": {
"kinds": [
"pdf",
"image",
],
"max_mb": 10,
"self_upload": True,
},
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "f1",
"key": "t_shirt_size",
"label": "Driving licence",
"type": "file",
"options": [
"S",
"M",
"L"
],
"tier": "public",
"archived": false,
"position": 1,
"file": null,
"target": "person",
"effective_dated": false,
"columns": null,
"analytics": false
}
}Change a custom field#
POST/v1/org/fields.updateWrite
Changes a custom field: label, tier (within what its target allows), options (select only; removing an option some records still hold is refused), columns (table only: send every current column with its key — labels and select options may change, options only grow — plus new ones; columns are never removed or retyped), file options (file only: kinds, max_mb, self_upload; they apply to new uploads, files already attached stay), position, or archived (archived fields are hidden from forms; their values are kept and included in personal-data exports, not in the people CSV). The key, type and target never change. Widening the tier (private to job or public, job to public) while records have values would show those values to more people: it is refused unless confirm_expose_existing is true, which is accepted only in the app, after the user confirmed.
- Who can call it
- Manage key owner admin hr
- Keys and apps
- confirm_expose_existing (widening a tier while people have values) is refused.
- MCP tool
org_fields_updateon HR Assistant- Preview
?dry_run=trueruns every check and saves nothing- Retries
- An Idempotency-Key replays the first result
Input
field_idstringrequiredlabelstring1–60 characters.
tier"public" | "job" | "private"optionsstring[]1–80 characters. 2–50 items.
positionintegerFrom 0 to 1000.
archivedbooleanfileobject3 fields
kinds"pdf" | "image" | "office"[]1–10 items.
max_mbinteger | nullFrom 1 to 100.
self_uploadboolean
columnsobject[]1–10 items.
4 fields
keystringDefaults to the label in snake_case; never changes.
Pattern
^[a-z][a-z0-9_]{0,39}$.labelstringrequired1–60 characters.
type"text" | "number" | "date" | "select" | "boolean"requiredoptionsstring[]select columns only: 2–50 options.
1–80 characters. 2–50 items.
analyticsbooleanUse in people analytics (aggregated only): the field becomes a dimension of Reports → People analytics, groups under the minimum size hidden, never listed per person and never given to API keys or AI apps. Select or yes/no fields on people or jobs only; refused for special-category data (GDPR Art. 9: health, ethnicity, religion, sexual orientation, disability, trade union, political opinions, biometric or genetic data).
confirm_expose_existingboolean
Returns
14 fields
idstringrequiredkeystringrequiredlabelstringrequiredtypestring (enum)requiredOne of:
text,number,date,select,boolean,file,person,table.optionsstring[]requiredtier"public" | "job" | "private"requiredarchivedbooleanrequiredpositionintegerrequiredfileobject | nullrequiredType file only; null for other types.
3 fields
kinds"pdf" | "image" | "office"[]requiredpdf (PDF), image (PNG, JPEG, WebP, HEIC), office (DOCX, XLSX, ODT, ODS).
max_mbinteger | nullrequiredThe field's largest file in MB; null = the company's limit. The smaller of the two applies.
self_uploadbooleanrequiredPeople upload their own file in Bizisy Me (it counts toward their monthly self-upload limit).
target"person" | "job" | "unit" | "position"requiredWhere values live: person (the profile), job (each job row: effective-dated), unit (a team) or position (an open position).
effective_datedbooleanrequiredValues follow the job timeline (job fields): a change from a date keeps the earlier value in history.
columnsobject[] | nullrequiredType table only: its columns; null for other types.
4 fields
keystringrequiredlabelstringrequiredtype"text" | "number" | "date" | "select" | "boolean"requiredoptionsstring[]required
analyticsbooleanrequiredUsable as a dimension in people analytics (aggregated only, groups under the minimum hidden; select and yes/no fields on people or jobs).
previous_tier"public" | "job" | "private"required
Errors
validation_failed unauthenticated forbidden not_found conflict rate_limited internal
curl https://api.bizisy.com/v1/org/fields.update \
-H "Authorization: Bearer $BIZISY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"field_id": "f1",
"tier": "job",
"options": [
"S",
"M",
"L",
"XL"
],
"position": 2,
"archived": true
}'const res = await fetch('https://api.bizisy.com/v1/org/fields.update', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.BIZISY_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': crypto.randomUUID(),
},
body: JSON.stringify({
"field_id": "f1",
"tier": "job",
"options": [
"S",
"M",
"L",
"XL"
],
"position": 2,
"archived": true
}),
});
const body = await res.json();
if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
console.log(body.data);import os, uuid
import requests
res = requests.post(
"https://api.bizisy.com/v1/org/fields.update",
headers={"Authorization": f"Bearer {os.environ['BIZISY_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
json={
"field_id": "f1",
"tier": "job",
"options": [
"S",
"M",
"L",
"XL",
],
"position": 2,
"archived": True,
},
)
body = res.json()
if not res.ok:
raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
print(body["data"]){
"data": {
"id": "f1",
"key": "t_shirt_size",
"label": "T-shirt size",
"type": "select",
"options": [
"S",
"M",
"L"
],
"tier": "job",
"archived": true,
"position": 2,
"file": null,
"target": "person",
"effective_dated": false,
"columns": null,
"analytics": false,
"previous_tier": "private"
}
}Something missing or wrong on this page? Write to hello@bizisy.com.