Custom fields

Create a custom field definition

Defines a new custom field on one kind of record. The options object decides the field's type and its validation rules, and the type cannot be inferred: you must send options.type.

POST

https://api.portal.magicdoor.com/company-app/custom-fields

Authorization

Authorizationstringrequired

Bearer token — Send your API token in the Authorization header as Bearer <token>. Requests without a valid token are rejected with 401 Unauthorized.

Body

application/json

entityTypeenum<string>required

What kind of record the field hangs off.

leaseunitpropertyportfoliocompanytenantvendormaintenanceRequestworkOrderbilltransactionchatchatMessagepropertyManagerunknownrentalApplicationleaseTemplateleaseDocumentassociationViolationownerunitListingfileworkOrderGroup

namestringrequired

Label shown next to the input, 1 to 100 characters.

descriptionstring

Help text, up to 500 characters.

publicbooleanrequired

Whether tenants, owners and vendors see the value in their own portals.

filterablebooleanrequired

Whether the field can be filtered on.

listablebooleanrequired

Whether the field can be shown as a list column.

orderintegerrequired

Where the field sits among the others. Lower sorts first.

optionsobjectrequired

The field's type and validation rules. type is the discriminator and decides which other properties are read.

Response

200 · The definition that was created.

idstring

The custom field definition. A Snowflake id sent as a decimal string.

entityTypeenum<string>

What kind of record this field can be set on.

namestring

Label shown next to the input.

descriptionstring

Help text. Absent when none was set.

publicboolean

Whether tenants, owners and vendors can see the value in their own portals.

filterableboolean

Whether the field can be filtered on in lists and reports.

listableboolean

Whether the field can be shown as a column in lists.

orderinteger

Where the field sits among the others. Lower sorts first.

optionsobject

The field's type and its validation rules.

activeboolean

Whether the field is still in use. A deactivated field keeps its stored values.

createdstring · date-time

When the field was created, in the company's timezone.

updatedstring · date-time

When it was last changed, in the company's timezone.

400 · `options.type` was missing or not one of the five known types, or a rule did not fit the type.

401 · The access token is missing, expired, or not valid for this company.

A custom field is a definition, not a value

This resource creates and edits the definitions: what the field is called, what kind of record it hangs off, and what a valid value looks like. The values themselves are set and read on the record they belong to, through that record's own endpoints.

Because the definitions are written by the company, a value has no single fixed type. Which JSON property carries it depends entirely on options.type on the definition.

`options.type`	Which value slot the field uses	Rules you can set
`string`	`stringValue`, or `stringArray` when `multiple` is true	`minLength`, `maxLength`, `values`, `rejectUnknown`, `multiline`, `multiple`, `default`
`number`	`numberValue`	`min`, `max`, `step`, `default`
`boolean`	`booleanValue`	`default`
`datetime`	`dateTimeValue`	`min`, `max`, `default`, `dateOnly`
`reference`	`referenceValue`, or `referenceArray` when `multiple` is true	`referenceEntityType`, `multiple`

So to read a value you first look up its definition by customFieldId, read options.type, and then read the matching property off the value. There is no generic value property.

Examples of each type

A picker with fixed choices

{
  "entityType": "lease",
  "name": "Parking space",
  "public": true,
  "filterable": true,
  "listable": true,
  "order": 10,
  "options": {
    "type": "string",
    "required": false,
    "values": ["None", "A1", "A2", "B1"],
    "rejectUnknown": true
  }
}

A bounded number

{
  "entityType": "unit",
  "name": "Storage lockers",
  "public": false,
  "filterable": true,
  "listable": false,
  "order": 20,
  "options": {
    "type": "number",
    "required": true,
    "min": 0,
    "max": 4,
    "step": 1,
    "default": 0
  }
}

A date

{
  "entityType": "property",
  "name": "Roof last inspected",
  "public": false,
  "filterable": true,
  "listable": true,
  "order": 30,
  "options": {
    "type": "datetime",
    "required": false,
    "dateOnly": true
  }
}

A pointer at another record

{
  "entityType": "lease",
  "name": "Preferred contractor",
  "public": false,
  "filterable": false,
  "listable": false,
  "order": 40,
  "options": {
    "type": "reference",
    "required": false,
    "referenceEntityType": "vendor",
    "multiple": false
  }
}