Add a field to a form. Types: text, textarea, integer, float, date, datetime, email, phone, url, select, checkbox, radio, file, image, location, autoincrement, yes_no, rel, formula, linked_column, linked_records, subform, map, action, divider, page_break, note, signature, country, language, states, time_zone, record_owners, matrix. A type's full parameters — get_field_types. ⚠️ For select/checkbox/radio ALWAYS pass choices in the SAME call — without them the field is not created.
View input schema
{
"type": "object",
"properties": {
"app_id": {
"type": "string",
"description": "Project ID"
},
"entity_id": {
"type": "string",
"description": "Form ID"
},
"name": {
"type": "string",
"description": "Field name"
},
"field_type": {
"type": "string",
"description": "Field type. Call get_field_types for the full list with descriptions."
},
"settings": {
"type": "object",
"description": "Any other setting of the field, as setting: value pairs in the product's own names — totals and averages under a column, barcode / QR code, an input mask, several files at once, a list's options side by side, pages of a long form, address help, edit in the table, how many fields share a row, a subform's rows (how many, the add link, hidden fields) and what the table shows of a subform or a list of linked records (one column or a small table of chosen columns, their order). Call get_field_types with field_type for the settings that fit one type. Example: {\"show_db_total_row\": true}. A setting that does not fit the field's type is refused by name."
},
"choices": {
"type": "array",
"items": {
"type": "string"
},
"description": "REQUIRED for select/checkbox/radio: an array of options. A call WITHOUT choices is refused with an error — do not make it; pass the options at once (take them from the user's words or propose sensible ones). Example: [\"New\", \"In progress\", \"Done\"]."
},
"default": {
"type": "string",
"description": "Default value (for select — one of the choices)"
},
"allow_new_values": {
"type": "boolean",
"description": "For select only. true — users can add new options right from the record form, without editing the field. Default false."
},
"required": {
"type": "boolean",
"description": "true — the field must be filled in"
},
"rel_entity_id": {
"type": "string",
"description": "ID of the form the rel field links to (required for rel)"
},
"rel_type": {
"type": "integer",
"description": "Link type (default 2): belongs_to=2/6/8 (dropdown/radio/multi), has_one=3/5/9 (dropdown/radio/multi), many-to-many=1/4 (autocomplete/checkboxes)"
},
"rel_show_field_id": {
"type": "string",
"description": "ID of the field to show in the rel dropdown (optional)"
},
"column": {
"type": "string",
"description": "REQUIRED for linked_column: the id of the field of the LINKED table that this column shows — «show the activity's description in the registration form» is a linked_column on Registrations with column = the id of Activities' Description (get_form_fields of that table lists the ids). The two tables must be linked already. Written here, beside settings — not inside settings"
},
"linked_entity_id": {
"type": "string",
"description": "The id of the other table: for linked_records / linked_records_count, and for a subform the table whose rows are filled in inside this form. A linked_column names its table by its column"
},
"entries_num": {
"type": "integer",
"description": "Number of linked records for linked_records (default 5)"
},
"start_from": {
"type": "integer",
"description": "Starting value of the autoincrement (default 1)"
},
"step": {
"type": "integer",
"description": "Step of the autoincrement (default 1)"
},
"formula_type": {
"type": "string",
"description": "Formula type: formula (arithmetic/concatenation), function (built-in functions + Ruby), link (clickable link), total (sum), average (average). REQUIRED for field_type=formula."
},
"total_table_column": {
"type": "string",
"description": "Not for a sum over the rows linked to this record — that is a linked_records field and a linked_column over it (937). formula_type total is refused by this tool."
},
"total_table_ref_column": {
"type": "string",
"description": "Not for a sum over the rows linked to this record (see total_table_column)."
},
"time_settings": {
"type": "object",
"description": "time field: how the time is picked. clock_system \"12h\" | \"24h\"; control_type \"dropdown\" | \"slider\"; units: { hour | minute | second | millisec | microsec: { show: true|false, min, max, step, grid } } — e.g. {\"units\": {\"minute\": {\"step\": 15}, \"second\": {\"show\": false}}}. Only what is passed changes"
},
"average_table_column": {
"type": "string",
"description": "Not for an average over the rows linked to this record: their sum (linked_records + linked_column) divided by a linked_records_count. formula_type average is refused by this tool."
},
"average_table_ref_column": {
"type": "string",
"description": "formula_type average: the link field in that other table that points at this form, by id or name; may be left out when only one table links here"
},
"operand_is": {
"type": "string",
"description": "Operand type for formula_type=formula: numbers, decimal, text, days, hours, year. REQUIRED when formula_type=formula."
},
"field": {
"type": "array",
"items": {
"type": "string"
},
"description": "Array of field IDs or constants ['Constant', 'text'] for formula_type=formula"
},
"operation": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operators between the fields: +, -, *, / (one fewer than the number of fields)"
},
"func": {
"type": "integer",
"description": "Function for formula_type=function: 0=MIN, 1=MAX, 2=ROUND_UP, 3=ROUND_DOWN, 4=Ruby script"
},
"func_fields": {
"type": "array",
"items": {
"type": "string"
},
"description": "IDs of all fields used in func/script_body. REQUIRED for formula_type=function — without it the formula is not recalculated."
},
"script_body": {
"type": "string",
"description": "Ruby code for func=4. Rules: the result goes into the variable 'a', the last line is 'a'; field names in single quotes 'field_name'.to_f; def/while/puts/return/require are forbidden; aggregating subforms through .to_f is FORBIDDEN (use linked_column for that)."
},
"not_add_space_between_operands": {
"type": "integer",
"description": "1 = no space between the operands (for concatenation without spaces)"
},
"formula_link_to": {
"type": "string",
"description": "formula_type=link: on_table or table_form"
},
"formula_link_target": {
"type": "string",
"description": "formula_type=link: _blank, _self, _parent, _top"
},
"formula_link_column": {
"type": "string",
"description": "formula_type=link: ID of the field with the table/form name"
},
"action_tasks": {
"type": "array",
"description": "Tasks of an Action field (field_type=action). task_type: 0=email, 1=sms, 2=update_record, 3=payment, 4=webhook, 5=open_form_or_url, 6=telegram/whatsapp. The full specification — get_field_types.",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "A unique task ID (for references from action_display_rules)"
},
"task_type": {
"type": "integer",
"description": "See task_type in the description of action_tasks above"
},
"update_fields": {
"type": "array",
"description": "Fields to update (task_type=2). Each object: {field_id, val, set_current_time, set_current_user}",
"items": {
"type": "object"
}
},
"email_from_template": {
"type": "boolean"
},
"email_template_id": {
"type": "string"
},
"email_recipient_source": {
"type": "integer",
"description": "0 = a list of emails, 1 = from a field, 2 = the record's owners"
},
"emails": {
"type": "string"
},
"email_column": {
"type": "string"
},
"subject": {
"type": "string"
},
"email_body": {
"type": "string"
},
"sms_from_template": {
"type": "boolean"
},
"sms_template_id": {
"type": "string"
},
"number_from_record": {
"type": "boolean"
},
"sms_column": {
"type": "string"
},
"sms_body": {
"type": "string"
},
"numbers": {
"type": "string"
},
"open_custom_url": {
"type": "boolean"
},
"custom_url": {
"type": "string"
},
"open_form_id": {
"type": "string"
},
"open_form_widget": {
"type": "boolean"
},
"redirect_to_new_page": {
"type": "boolean"
},
"message_from_template": {
"type": "boolean"
},
"message_recipient_source": {
"type": "integer"
},
"telegram_template_id": {
"type": "string"
},
"whatsapp_template_id": {
"type": "string"
},
"message": {
"type": "string"
},
"webhook": {
"type": "object",
"description": "Webhook config: {request_method(0-4), auth_type(0-2), url, webhook_params[], webhook_headers[]}"
},
"payment_workflow": {
"type": "object",
"description": "Payment config: {merchant_type(0=paypal,1=braintree), amount_field_id, business_email, currency, ...}"
}
},
"required": [
"task_type"
]
}
},
"action_display_rules": {
"type": "array",
"description": "Rules for when the Action button is shown. For all records — do not pass this array.",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"criteria_name": {
"type": "string",
"description": "Description of the criteria (required)"
},
"action_task_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Task IDs from action_tasks"
},
"action_type": {
"type": "integer",
"description": "0=link, 1=button"
},
"action_color": {
"type": "integer",
"description": "0=primary,1=secondary,2=success,3=danger,4=info,5=warning,6=light,7=dark"
},
"action_size": {
"type": "integer",
"description": "0=small,1=medium,2=large"
},
"icon": {
"type": "string",
"description": "A FontAwesome class, e.g. 'fas fa-check'"
},
"conditions": {
"type": "array",
"description": "Display conditions (empty = for all records). {property_id, condition, search, join: and|or}",
"items": {
"type": "object"
}
}
},
"required": [
"name",
"action_task_ids"
]
}
},
"action_type": {
"type": "integer",
"description": "action field: 0=link(default), 1=button"
},
"action_color": {
"type": "integer",
"description": "action field: 0=primary,2=success,3=danger,6=light(default)"
},
"action_size": {
"type": "integer",
"description": "action field: 0=small,1=medium(default),2=large"
},
"action_fill": {
"type": "integer",
"description": "action field: 0=inline(default), 1=block"
},
"icon": {
"type": "string",
"description": "action field: the icon's FontAwesome class"
},
"action_done_message": {
"type": "string",
"description": "action field: the message after the task is done"
},
"hide_column_name": {
"type": "boolean",
"description": "action/formula: hide the column's name in the table"
},
"add_to_actions_control": {
"type": "boolean",
"description": "action: add to the bulk actions menu"
},
"action_name_from_column": {
"type": "boolean",
"description": "action: the button's caption is taken from a field of the record (action_name_column_id) instead of the field's name"
},
"action_name_column_id": {
"type": "string",
"description": "action: the id of the field of this form whose value is the button's caption — with action_name_from_column true"
},
"icon_align": {
"type": "integer",
"description": "action: where the icon stands beside the caption — 1 left (default), 2 right"
},
"matrix_rows": {
"type": "array",
"items": {
"type": "string"
},
"description": "Matrix rows (field_type=matrix)"
},
"matrix_columns": {
"type": "array",
"items": {
"type": "string"
},
"description": "Matrix columns (field_type=matrix)"
},
"desc": {
"type": "string",
"description": "A tooltip hint for the person filling in the form"
},
"text_align": {
"type": "integer",
"description": "Alignment in the cell: 1=left, 2=right, 3=center, 4=justify"
},
"vertical_align": {
"type": "integer",
"description": "Vertical alignment: 1=top, 2=middle, 3=bottom"
},
"truncates_after": {
"type": "integer",
"description": "Cut the text in the table after N characters (default 1000)"
},
"visible": {
"type": "boolean",
"description": "false — the field's column is not shown on the table's PUBLIC page (the page, a found record, one record's own page). Signed in, the owner still sees it in their own table and in the form. For a public page prefer update_public_page hide_columns: it takes the field out of the page's search too"
},
"rich": {
"type": "boolean",
"description": "true — a text editor (for field_type=textarea)"
},
"precision": {
"type": "integer",
"description": "Digits after the decimal point for float (default 2)"
},
"separator": {
"type": "string",
"description": "Decimal separator: '.' or ','"
},
"delimiter": {
"type": "string",
"description": "Thousands separator: '' or ',' or '.'"
},
"is_currency": {
"type": "boolean",
"description": "Show as currency"
},
"currency_unit": {
"type": "string",
"description": "Currency symbol: '$', '€', '₴' and so on"
},
"add_percent_to_number": {
"type": "boolean",
"description": "Add a % sign after the number"
},
"disable_future": {
"type": "boolean",
"description": "Forbid choosing future dates (for date/datetime/dob)"
},
"disable_past": {
"type": "boolean",
"description": "Forbid choosing past dates (for date/datetime/dob)"
},
"ampm": {
"type": "boolean",
"description": "true — 12-hour format (AM/PM) for time/datetime"
},
"default_type": {
"type": "integer",
"description": "0 = fixed, 1 = current date/time (date/datetime), 2 = current user (record_owners)"
},
"dependent": {
"type": "boolean",
"description": "rel only: true — the list offers only the rows linked to what another field of the same form holds (Country → City, Stage → Check point); give depends_from_field_id with it. get_field_types with field_type rel says the shape"
},
"depends_from_field_id": {
"type": "string",
"description": "rel only: the field of the same form (name or id) whose pick narrows this list — itself a link to a table that the linked table links to as well"
},
"linked_records_count_form_id": {
"type": "string",
"description": "ID of the form to count (required for field_type=linked_records_count)"
},
"uniqueness": {
"type": "object",
"description": "Check that the field's values are unique.",
"properties": {
"uniq_type": {
"type": "integer",
"description": "0 = none, 1 = strictly unique, 2 = multi (a combination of fields)"
},
"linked_fields": {
"type": "array",
"items": {
"type": "string"
},
"description": "For uniq_type=2: an array of names or IDs of the other fields"
},
"error_message": {
"type": "string",
"description": "A custom message when uniqueness is broken"
}
}
},
"display_as_image": {
"type": "boolean",
"description": "true — show the URL as a picture (field_type=url only, for photos)"
},
"validations": {
"type": "object",
"description": "The field's checks. required: true is the shorter way to make it required. They check the text typed into the add or edit form, in the browser: none reads a date's weekday, a holiday, opening hours or other records (see the instruction's VALIDATIONS).",
"properties": {
"Email": {
"type": "string",
"description": "\"1\" — check the email format"
},
"URL": {
"type": "string",
"description": "\"on\" — check the URL format"
},
"LOCATION": {
"type": "string",
"description": "\"1\" — check the geolocation"
},
"onlyOnSubmit": {
"type": "string",
"description": "\"1\" — validate only on submit, not while typing"
},
"format": {
"type": "string",
"description": "A regexp in the form /^regex$/ — check against a regular expression"
},
"minimum": {
"description": "Minimum: for text — the number of characters; for integer/float — the numeric value"
},
"maximum": {
"description": "Maximum: for text — the number of characters; for integer/float — the numeric value"
},
"is": {
"description": "Exact length (for text) or exact value (for number)"
},
"Inclusion": {
"type": "string",
"description": "Allowed values, comma-separated: \"Admin, Manager, User\""
},
"inclusion_caseSensitive": {
"type": "string",
"description": "\"on\" — case-sensitive Inclusion"
},
"inclusion_partialMatch": {
"type": "string",
"description": "\"on\" — partial match in Inclusion"
},
"inclusion_allowNull": {
"type": "string",
"description": "\"on\" — allow an empty value in Inclusion"
},
"Exclusion": {
"type": "string",
"description": "Forbidden values, comma-separated: \"spam, abuse\""
},
"exclusion_caseSensitive": {
"type": "string",
"description": "\"on\" — case-sensitive Exclusion"
},
"exclusion_partialMatch": {
"type": "string",
"description": "\"on\" — partial match in Exclusion"
},
"exclusion_allowNull": {
"type": "string",
"description": "\"on\" — allow an empty value in Exclusion"
}
}
}
},
"required": [
"app_id",
"entity_id",
"name",
"field_type"
]
}