Skip to content

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

Input

  • include_archivedboolean
  • target"person" | "job" | "unit" | "position"

Returns

An array of objects with 13 fields

An array of objects:

  • idstringrequired
  • keystringrequired
  • labelstringrequired
  • typestring (enum)required

    One of: text, number, date, select, boolean, file, person, table.

  • optionsstring[]required
  • tier"public" | "job" | "private"required
  • archivedbooleanrequired
  • positionintegerrequired
  • fileobject | nullrequired

    Type file only; null for other types.

    3 fields
    • kinds"pdf" | "image" | "office"[]required

      pdf (PDF), image (PNG, JPEG, WebP, HEIC), office (DOCX, XLSX, ODT, ODS).

    • max_mbinteger | nullrequired

      The field's largest file in MB; null = the company's limit. The smaller of the two applies.

    • self_uploadbooleanrequired

      People upload their own file in Bizisy Me (it counts toward their monthly self-upload limit).

  • target"person" | "job" | "unit" | "position"required

    Where values live: person (the profile), job (each job row: effective-dated), unit (a team) or position (an open position).

  • effective_datedbooleanrequired

    Values follow the job timeline (job fields): a change from a date keeps the earlier value in history.

  • columnsobject[] | nullrequired

    Type table only: its columns; null for other types.

    4 fields
    • keystringrequired
    • labelstringrequired
    • type"text" | "number" | "date" | "select" | "boolean"required
    • optionsstring[]required
  • analyticsbooleanrequired

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

Input

  • labelstringrequired

    1–60 characters.

  • typestring (enum)required

    One 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"
  • keystring

    Pattern ^[a-z][a-z0-9_]{0,39}$.

  • fileobject
    3 fields
    • kinds"pdf" | "image" | "office"[]

      1–10 items.

    • max_mbinteger | null

      From 1 to 100.

    • self_uploadboolean
  • columnsobject[]

    1–10 items.

    4 fields
    • keystring

      Defaults to the label in snake_case; never changes.

      Pattern ^[a-z][a-z0-9_]{0,39}$.

    • labelstringrequired

      1–60 characters.

    • type"text" | "number" | "date" | "select" | "boolean"required
    • optionsstring[]

      select columns only: 2–50 options.

      1–80 characters. 2–50 items.

  • analyticsboolean

    Use 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
  • idstringrequired
  • keystringrequired
  • labelstringrequired
  • typestring (enum)required

    One of: text, number, date, select, boolean, file, person, table.

  • optionsstring[]required
  • tier"public" | "job" | "private"required
  • archivedbooleanrequired
  • positionintegerrequired
  • fileobject | nullrequired

    Type file only; null for other types.

    3 fields
    • kinds"pdf" | "image" | "office"[]required

      pdf (PDF), image (PNG, JPEG, WebP, HEIC), office (DOCX, XLSX, ODT, ODS).

    • max_mbinteger | nullrequired

      The field's largest file in MB; null = the company's limit. The smaller of the two applies.

    • self_uploadbooleanrequired

      People upload their own file in Bizisy Me (it counts toward their monthly self-upload limit).

  • target"person" | "job" | "unit" | "position"required

    Where values live: person (the profile), job (each job row: effective-dated), unit (a team) or position (an open position).

  • effective_datedbooleanrequired

    Values follow the job timeline (job fields): a change from a date keeps the earlier value in history.

  • columnsobject[] | nullrequired

    Type table only: its columns; null for other types.

    4 fields
    • keystringrequired
    • labelstringrequired
    • type"text" | "number" | "date" | "select" | "boolean"required
    • optionsstring[]required
  • analyticsbooleanrequired

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

Input

  • field_idstringrequired
  • labelstring

    1–60 characters.

  • tier"public" | "job" | "private"
  • optionsstring[]

    1–80 characters. 2–50 items.

  • positioninteger

    From 0 to 1000.

  • archivedboolean
  • fileobject
    3 fields
    • kinds"pdf" | "image" | "office"[]

      1–10 items.

    • max_mbinteger | null

      From 1 to 100.

    • self_uploadboolean
  • columnsobject[]

    1–10 items.

    4 fields
    • keystring

      Defaults to the label in snake_case; never changes.

      Pattern ^[a-z][a-z0-9_]{0,39}$.

    • labelstringrequired

      1–60 characters.

    • type"text" | "number" | "date" | "select" | "boolean"required
    • optionsstring[]

      select columns only: 2–50 options.

      1–80 characters. 2–50 items.

  • analyticsboolean

    Use 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
  • idstringrequired
  • keystringrequired
  • labelstringrequired
  • typestring (enum)required

    One of: text, number, date, select, boolean, file, person, table.

  • optionsstring[]required
  • tier"public" | "job" | "private"required
  • archivedbooleanrequired
  • positionintegerrequired
  • fileobject | nullrequired

    Type file only; null for other types.

    3 fields
    • kinds"pdf" | "image" | "office"[]required

      pdf (PDF), image (PNG, JPEG, WebP, HEIC), office (DOCX, XLSX, ODT, ODS).

    • max_mbinteger | nullrequired

      The field's largest file in MB; null = the company's limit. The smaller of the two applies.

    • self_uploadbooleanrequired

      People upload their own file in Bizisy Me (it counts toward their monthly self-upload limit).

  • target"person" | "job" | "unit" | "position"required

    Where values live: person (the profile), job (each job row: effective-dated), unit (a team) or position (an open position).

  • effective_datedbooleanrequired

    Values follow the job timeline (job fields): a change from a date keeps the earlier value in history.

  • columnsobject[] | nullrequired

    Type table only: its columns; null for other types.

    4 fields
    • keystringrequired
    • labelstringrequired
    • type"text" | "number" | "date" | "select" | "boolean"required
    • optionsstring[]required
  • analyticsbooleanrequired

    Usable 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
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
}'
Response
{
  "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.

Developer docs