Add form

Adds a form to a database.

Request

POST https://www.activityinfo.org/resources/databases/{databaseId}/forms

Request body

application/json

object
formResource	object		required
id	string	The resource's id. Form and subform resources must have globally-unique ids (across all of ActivityInfo) but folder ids are only guaranteed to be unique within a single database.	required
type	string	The resource type. Values: DATABASE FOLDER REPORT FORM SUB_FORM	required
parentId	string	The id of this resource's parent, for example, a folder id. If this is a top-level folder or form, the the parentId will be the id of the database itself.	required
label	string	The resource's human-readable label.	required
visibility	string	The resource's visibility. Values: PUBLIC Public. Visible to all Users on system, regardless of assigned permissions. PRIVATE Visible only to users given explicit permissions. REFERENCE Visible only if another Resource on the Database is visible to the current User. Used to provide Forms with data to be referenced, but not requiring an explicit grant to be generated for the User.	required
formClass	object		required
id	string	The immutable CUID for this form. Must be globally unique within an ActivityInfo server	required
label	string	A human-readable label for this form	required
schemaVersion	string	A monotonically increasing version number of this schema assigned by the server upon updates	required
databaseId	string	The id of the database to which this form belongs	required
parentFormId	string	The id of this form's parent, if this form is a subform. Note that subforms can only be created by adding a subform field to the parent form.	optional
elements	array[object]	This form's fields, section headers, and other elements.	required
id	string	An immutable CUID for this field that is unique within the form	required
code	string	A developer-friendly code for this field that can be used in formulas and in the API. Must match the pattern ^[A-Za-z][A-Za-z0-9_]*	optional
label	string	A short human-friendly label for this field	required
description	string	A longer description of the field, shown to users during data entry as help text.	optional
relevanceCondition	string	A boolean-valued ActivityInfo formula that determines when this field is 'relevant'. Fields that are not relevant are not displayed during data entry and must be blank.	optional
requiredCondition	string	A boolean-valued ActivityInfo formula that, when this field is required, limits the requirement to the records for which the formula is satisfied. When omitted, a required field is required for every record.	optional
validationCondition	string	A boolean-valued ActivityInfo formula that determines when this field's value is valid.	optional
validationMessage	string	A custom error message shown when this field's validation condition fails. When omitted, an automatically composed message is shown instead.	optional
dataEntryVisible	boolean	If false, this field is not shown in data entry	optional
tableVisible	boolean	If false, this field is not shown by default in the table view	optional
required	boolean	If true, a value for this field must be provided	required
key	boolean	If true, this field is part of the form's natural key fields whose combination must be unique within the form	required
readOnly	boolean	If true, this field is shown but cannot be edited during data entry. Default is false.	optional
unique	boolean	If true, the value of this field must be unique within the form. Default is false.	optional
metadata	string	For a metadata field, the kind of record metadata that the server stores in it: ADDED_BY (the user who first saved the record) or LAST_EDITED_BY (the user who last edited it). A metadata field is always read-only, must be a reference to the database's users form, and has a fixed id per kind (_addedBy, _lastEditedBy). Its value cannot be set through the API, import or data entry; when the field is added to a form with existing records, it is filled in from the record history.	optional
type	string	The field type Values: serial A read-only, incrementing serial number for new records. month Stores a month in the ISO-8601 calendar without reference to time-of-day or time-zone. attachment Stores one or more files, which can include photos, signatures, documents, PDFs or any other type of file. geopoint Stores a point within the WGS84 Geographic Reference System FREE_TEXT Stores a single line of Unicode text quantity Stores a real-valued number as a floating point enumerated Gives users a choice between a list of predefined values multiselectreference Stores a reference to one or more records in another form epiweek Stores a year and week number. subform Defines a reference to another form that plays a child role to this parent form. date Stores a date in the ISO-8601 calendar without reference to time-of-day or time-zone. calculated A read-only field whose value is always calculated from a formula reversereference Defines a reverse link from a referenced form back to this form. note Defines a note that displays a label and description at data collection time. Does not capture a value. reference Stores a reference to one record in another form fortnight Stores a two-week period using year and a week number, where the week number must be odd. [Deprecated] section Defines a section header that helps organize a form. Does not have a field value. NARRATIVE Stores multiple lines of Unicode text	required
securityCategoryId	string		optional
typeParameters	object	Additional type-specific properties of this field.	optional
units	string	For fields of type 'quantity', describes the units of the quantity.	optional
inputMask	string	For text fields, provides a pattern-based input mask.	optional
barcode	boolean	For text fields, when true the field is rendered as a barcode-scanner input during data entry.	optional
cardinality	string	For fields of type 'enumerated' or 'attachment', indicates whether single or multiple selection is allowed. Values: SINGLE At most one instance may linked to the field MULTIPLE Any number of instances may be linked to the field	optional
presentation	string	For fields of type 'enumerated', controls how the choices are rendered (automatic, radio_button, or dropdown). Values: AUTOMATIC RADIO_BUTTON DROPDOWN	optional
values	array[object]	For fields of type 'enumerated', the list of valid choices.	optional
id	string	The immutable CUID of this selection item. Must match the format [a-z][a-z0-9]{0,25} and be unique within this field.	required
label	string	Human-readable label for this selection item.	required
range	array[object]	For fields of type 'reference' or 'multiselectreference', the form this field references. Always exactly one entry: the array shape is a legacy of an older version that allowed a single field to reference multiple forms.	optional
formId	string	The id of a form referenced by this entry.	required
lookupConfigs	array[object]	For fields of type 'reference', overrides how referenced records are looked up during data entry. Each entry pairs a formula selecting candidate records with a label.	optional
id	string	Unique id for this lookup configuration	required
formula	string	A formula that will be used to lookup records. It can be a simple field reference, or a more complex formula.	required
lookupLabel	string	A label which describes the lookup. Used in the data entry, table view and other places where the lookup is displayed.	required
formId	string	For fields of type 'subform', the id of the sub form that this field references. For 'reversereference' fields, the id of the form holding the reference field that points back to records of this form.	optional
fieldId	string	For fields of type 'reversereference', the id of the reference field on the form named by 'formId' that points back to records of this form.	optional
formula	string	For fields of type 'calculated', the formula for the field's value.	optional
prefixFormula	string	For fields of type 'serial', a formula whose value becomes the prefix of generated serial numbers.	optional
captureMethods	array[string]	For fields of type 'attachment', the input methods enabled during data entry. Values: FILE SIGNATURE CAMERA AUDIO	optional
fileTypes	array[string]	For fields of type 'attachment', when the 'file' capture method is enabled, restricts uploads to files whose content matches one of the listed categories. An empty or omitted array means any file type is accepted. Note: content-based enforcement currently runs on self-managed (standalone) deployments; on hosted accounts the field is detected and persisted but downloads are not yet gated. Values: PDF IMAGE OFFICE_DOCUMENT VIDEO AUDIO	optional
requiredAccuracy	float	For fields of type 'geopoint', the minimum accuracy in meters required when capturing a point from the device's GPS.	optional
indentationLevel	integer	For fields of type 'section' (section headers), the number of levels by which the section header is indented in the form layout.	optional
translationConfig	object	For fields of type 'FREE_TEXT', 'NARRATIVE', or 'calculated', associates this field with a translation field that holds its translations into other languages.	optional
fieldId	string		required
languages	array[string]		required
defaultValue	object	A default value to pre-populate this field with when a new record is created. The structure depends on the field's type.	optional
defaultValueFormula	string	An ActivityInfo formula evaluated when a new record is created; the result becomes the field's default value.	optional

Successful response

application/json

object
database	object		required
databaseId	string	This database's id	required
userId	string	The id of the requesting user. The contents of the tree depends on the permissions of the requesting user.	optional
version	string	The monotonically-increasing version of the database tree. The version number is incremented whenever a change is made that affects the database tree.	required
label	string	This database's human-readable label.	required
description	string		required
ownerRef	object	The database's individual owner, if it still has one. Absent for databases that are administered through roles alone.	optional
id	string		required
name	string		required
email	string		required
language	string	Current database language	required
originalLanguage	string	Original database language	optional
languages	array[string]	The languages that have been defined for this database translation.	required
suspended	boolean	True if this database is suspended for billing reasons	required
features	array[string]	The features enabled on this database that all users may see. Administrator-only features are read through the database settings API instead. Values: MCP_SERVER The in-server MCP endpoint may expose this database to AI assistants. Only administrators see it: it's needed when admitting MCP clients, not when rendering the database. INTERACTIVE_DEFAULT Forms without a shared default view open the table in interactive mode by default.	required
role	object	The requesting user's assigned role in this database.	required
roleId	string	The id of the role assigned to this user.	required
roleParameters	object	The values of the parameters defined for this role.	required
roleResources	array[string]	The resources (database, folder, forms, or subforms) to which the role's permissions are to apply.	required
roles	array[object]	The roles that have been defined for this database.	required
id	string	This role's id	required
label	string	This role's human-readable label	required
permissions	array[object]	Permissions granted this role. Applicable for legacy roles, for grant based roles it will be limited to permissions that are NOT related to resources, like MANAGE_USERS, MANAGE_ROLES	required
operation	string	Values: VIEW View the resource, whether a form, folder, or database. DISCOVER Find the resource in the list of forms in the user interface ADD_RECORD Add a record within a form contained by this folder or form. EDIT_RECORD Edit a record's values within a form contained by this folder or form. MANAGE_REFERENCE_DATA Add, edit, and delete records within reference forms DELETE_RECORD Delete a record within this form. BULK_DELETE Bulk record delete within this form EXPORT_RECORDS Export Records from a form, folder or database. MANAGE_USERS Grant permissions to a user to this database, folder, or form. LOCK_RECORDS Add, modify, or remove locks on records. ADD_RESOURCE Create a new Resource (Form or Folder) EDIT_RESOURCE Edit a Resource's schema, structure, attributes or data. DELETE_RESOURCE Delete a Resource (Form or Folder) MANAGE_COLLECTION_LINKS Manage (open/close) collection links for the given form AUDIT Access the Audit logs for a database (or a subset) SHARE_REPORTS Allow the user to share reports with other roles in the database. PUBLISH_REPORTS Allows the user to publish reports. MANAGE_ROLES Add, modify and delete roles MANAGE_AUTOMATIONS View, add, modify and delete automations MANAGE_TRANSLATIONS Allows the user to manage the translations. RESOLVE_DUPLICATES View and merge duplicate records SHARE_VIEWS Allow the user to share views with other users in the database. MANAGE_IMPORT_CONFIGS Allow the user to view and manage saved import configurations on the resource. SECURITY_CONTACT Receive the security notifications for this database: support-access claims, compromised-user alerts and the periodic risk report. A database-level permission carried by a role; it grants no access to data on its own. VIEW_FIELD Allow the user to view a field's data. EDIT_FIELD Allow the user to modify a field's data.	required
filter	string	A formula which restricts a permission to specific records. Only record-level permissions can be filtered.	optional
securityCategories	array[string]		required
parameters	array[object]	Parameters defined for this role. Parameters can be referenced in filtering formulas.	required
parameterId	string		required
label	string		required
range	string		required
filters	array[object]	Pre-defined filters. Role filters allow other users to choose filters for permissions without having to write formulas themselves. -- NOTEWORTHY - only used by legacy roles	required
id	string	This filter's id.	required
label	string	This filter's human-readable label	required
filter	string	A formula that can be used to filter a record-level permission.	required
grants	array[object]		required
resourceId	string		required
operations	array[string]		required
assignableRoles	array[string]	Ids of the roles that holders of this role may assign to, or remove from, other users. Holders must also hold the MANAGE_USERS permission. This explicit list is ignored when assignAnyRole is true, and for legacy roles. Ids of roles that no longer exist are ignored.	required
assignAnyRole	boolean	When true, holders of this role may assign any role in the database, including roles created later. When false, only the roles listed in assignableRoles may be assigned.	required
securityCategories	array[object]	The security categories that have been defined for this database.	required
id	string	This security category's id	required
label	string	This security category's human-readable label	required
resources	array[object]	The set of resources (folders, forms, and subforms) that belong to this database.	required
id	string	The resource's id. Form and subform resources must have globally-unique ids (across all of ActivityInfo) but folder ids are only guaranteed to be unique within a single database.	required
type	string	The resource type. Values: DATABASE FOLDER REPORT FORM SUB_FORM	required
parentId	string	The id of this resource's parent, for example, a folder id. If this is a top-level folder or form, the the parentId will be the id of the database itself.	required
label	string	The resource's human-readable label.	required
visibility	string	The resource's visibility. Values: PUBLIC Public. Visible to all Users on system, regardless of assigned permissions. PRIVATE Visible only to users given explicit permissions. REFERENCE Visible only if another Resource on the Database is visible to the current User. Used to provide Forms with data to be referenced, but not requiring an explicit grant to be generated for the User.	required
locks	array[object]	The record locks that have been defined on this database.	required
id	string	This lock's id.	required
label	string	A human-readable label for this lock	required
resourceId	string	The resource (database, folder, form, or subform) to which this lock applies.	required
dateRange	object	The date range to which this lock applies.	optional
startDate	local_date		required
endDate	local_date		required
formula	string	The formula to which this rule based lock applies.	optional
message	string	user description of the rule based lock.	optional
deactivated	boolean		required
grants	array[object]	The permission grants that have been made to the requesting user for this database.	required
resourceId	string		required
operations	array[string]		required
billingAccountId	integer		required
billingPlan	string	The billing plan name under which this database falls. The billing plan can have an affect on which features are avialable within this database.	required
forms	array[object]		required
id	string	The id of the form	required
visible	boolean	True if the form is visible to the authenticated user	required
deleted	boolean	True if the form has been deleted	required
schema	object		required
id	string	The immutable CUID for this form. Must be globally unique within an ActivityInfo server	required
label	string	A human-readable label for this form	required
schemaVersion	string	A monotonically increasing version number of this schema assigned by the server upon updates	required
databaseId	string	The id of the database to which this form belongs	required
parentFormId	string	The id of this form's parent, if this form is a subform. Note that subforms can only be created by adding a subform field to the parent form.	optional
elements	array[object]	This form's fields, section headers, and other elements.	required
id	string	An immutable CUID for this field that is unique within the form	required
code	string	A developer-friendly code for this field that can be used in formulas and in the API. Must match the pattern ^[A-Za-z][A-Za-z0-9_]*	optional
label	string	A short human-friendly label for this field	required
description	string	A longer description of the field, shown to users during data entry as help text.	optional
relevanceCondition	string	A boolean-valued ActivityInfo formula that determines when this field is 'relevant'. Fields that are not relevant are not displayed during data entry and must be blank.	optional
requiredCondition	string	A boolean-valued ActivityInfo formula that, when this field is required, limits the requirement to the records for which the formula is satisfied. When omitted, a required field is required for every record.	optional
validationCondition	string	A boolean-valued ActivityInfo formula that determines when this field's value is valid.	optional
validationMessage	string	A custom error message shown when this field's validation condition fails. When omitted, an automatically composed message is shown instead.	optional
dataEntryVisible	boolean	If false, this field is not shown in data entry	optional
tableVisible	boolean	If false, this field is not shown by default in the table view	optional
required	boolean	If true, a value for this field must be provided	required
key	boolean	If true, this field is part of the form's natural key fields whose combination must be unique within the form	required
readOnly	boolean	If true, this field is shown but cannot be edited during data entry. Default is false.	optional
unique	boolean	If true, the value of this field must be unique within the form. Default is false.	optional
metadata	string	For a metadata field, the kind of record metadata that the server stores in it: ADDED_BY (the user who first saved the record) or LAST_EDITED_BY (the user who last edited it). A metadata field is always read-only, must be a reference to the database's users form, and has a fixed id per kind (_addedBy, _lastEditedBy). Its value cannot be set through the API, import or data entry; when the field is added to a form with existing records, it is filled in from the record history.	optional
type	string	The field type Values: serial A read-only, incrementing serial number for new records. month Stores a month in the ISO-8601 calendar without reference to time-of-day or time-zone. attachment Stores one or more files, which can include photos, signatures, documents, PDFs or any other type of file. geopoint Stores a point within the WGS84 Geographic Reference System FREE_TEXT Stores a single line of Unicode text quantity Stores a real-valued number as a floating point enumerated Gives users a choice between a list of predefined values multiselectreference Stores a reference to one or more records in another form epiweek Stores a year and week number. subform Defines a reference to another form that plays a child role to this parent form. date Stores a date in the ISO-8601 calendar without reference to time-of-day or time-zone. calculated A read-only field whose value is always calculated from a formula reversereference Defines a reverse link from a referenced form back to this form. note Defines a note that displays a label and description at data collection time. Does not capture a value. reference Stores a reference to one record in another form fortnight Stores a two-week period using year and a week number, where the week number must be odd. [Deprecated] section Defines a section header that helps organize a form. Does not have a field value. NARRATIVE Stores multiple lines of Unicode text	required
securityCategoryId	string		optional
typeParameters	object	Additional type-specific properties of this field.	optional
units	string	For fields of type 'quantity', describes the units of the quantity.	optional
inputMask	string	For text fields, provides a pattern-based input mask.	optional
barcode	boolean	For text fields, when true the field is rendered as a barcode-scanner input during data entry.	optional
cardinality	string	For fields of type 'enumerated' or 'attachment', indicates whether single or multiple selection is allowed. Values: SINGLE At most one instance may linked to the field MULTIPLE Any number of instances may be linked to the field	optional
presentation	string	For fields of type 'enumerated', controls how the choices are rendered (automatic, radio_button, or dropdown). Values: AUTOMATIC RADIO_BUTTON DROPDOWN	optional
values	array[object]	For fields of type 'enumerated', the list of valid choices.	optional
id	string	The immutable CUID of this selection item. Must match the format [a-z][a-z0-9]{0,25} and be unique within this field.	required
label	string	Human-readable label for this selection item.	required
range	array[object]	For fields of type 'reference' or 'multiselectreference', the form this field references. Always exactly one entry: the array shape is a legacy of an older version that allowed a single field to reference multiple forms.	optional
formId	string	The id of a form referenced by this entry.	required
lookupConfigs	array[object]	For fields of type 'reference', overrides how referenced records are looked up during data entry. Each entry pairs a formula selecting candidate records with a label.	optional
id	string	Unique id for this lookup configuration	required
formula	string	A formula that will be used to lookup records. It can be a simple field reference, or a more complex formula.	required
lookupLabel	string	A label which describes the lookup. Used in the data entry, table view and other places where the lookup is displayed.	required
formId	string	For fields of type 'subform', the id of the sub form that this field references. For 'reversereference' fields, the id of the form holding the reference field that points back to records of this form.	optional
fieldId	string	For fields of type 'reversereference', the id of the reference field on the form named by 'formId' that points back to records of this form.	optional
formula	string	For fields of type 'calculated', the formula for the field's value.	optional
prefixFormula	string	For fields of type 'serial', a formula whose value becomes the prefix of generated serial numbers.	optional
captureMethods	array[string]	For fields of type 'attachment', the input methods enabled during data entry. Values: FILE SIGNATURE CAMERA AUDIO	optional
fileTypes	array[string]	For fields of type 'attachment', when the 'file' capture method is enabled, restricts uploads to files whose content matches one of the listed categories. An empty or omitted array means any file type is accepted. Note: content-based enforcement currently runs on self-managed (standalone) deployments; on hosted accounts the field is detected and persisted but downloads are not yet gated. Values: PDF IMAGE OFFICE_DOCUMENT VIDEO AUDIO	optional
requiredAccuracy	float	For fields of type 'geopoint', the minimum accuracy in meters required when capturing a point from the device's GPS.	optional
indentationLevel	integer	For fields of type 'section' (section headers), the number of levels by which the section header is indented in the form layout.	optional
translationConfig	object	For fields of type 'FREE_TEXT', 'NARRATIVE', or 'calculated', associates this field with a translation field that holds its translations into other languages.	optional
fieldId	string		required
languages	array[string]		required
defaultValue	object	A default value to pre-populate this field with when a new record is created. The structure depends on the field's type.	optional
defaultValueFormula	string	An ActivityInfo formula evaluated when a new record is created; the result becomes the field's default value.	optional
permissions	object		required
suspended	boolean	True if the form belongs to a suspended database.	required
backfillJob	object	The job the server started to fill in metadata fields that this change added to a form with existing records; absent when no such field was added.	optional
id	string	The job's id	required
userId	string	The id of the user who started the job	required
descriptor	object	The job descriptor used to start this job	required
state	string	The job's current state Values: STARTED The job has started processing. COMPLETED The job has completed successfully. FAILED The job has failed.	required
jobResult	object		required
percentComplete	float		required
error	object	If the job state is FAILED, the reason for the failure.	optional
code	string		required
message	string		required
localizedMessage	string		required
startTime	instant	The time at which the job was started, in milliseconds since the epoch. Zero for statuses that were recorded before start times were reported.	required
completionTime	instant	The time at which the job completed or failed, in milliseconds since the epoch. Absent while the job is pending.	optional
read	boolean	True if the user has seen this job's outcome, for example by downloading its result or by marking its notification as read.	required

Error responses

Status Code	Error Code	Description
401	AUTHENTICATION_REQUIRED	The request must be authenticated

Next item

Audit database