APIAPICreate a copy of an existing form, including all of its elements, layout, and conditional logic. By default, the copy's name is prefixed with "[Copy]" and its status is set to "draft". Both can be overridden. Returns the full duplicated form document.
AuthorizationRequiredBearer <token>API key as Bearer token
In: header
application/jsonRequirednamestringIf specified, the duplicated form will have the given name. Otherwise, a
default name will be generated by prefixing the existing name with "[Copy]".statusstringIf specified, the new form will have the given status. Otherwise, the new form will be a draft by default.
"draft" | "active" | "archived"formIdRequiredstringThe ID of the form.
curl -X POST "https://api.3common.com/v1/forms/string/duplicate" \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"name": "string",
"status": "draft"
}'{
"data": {
"id": "string",
"name": "string",
"nameHidden": true,
"ownerId": "string",
"status": "draft",
"rows": [
{
"columns": [
{
"elementIndex": 0,
"widthFraction": 0
}
]
}
],
"submitButtonText": "string",
"submitButtonWidth": "auto",
"submitButtonAlign": "left",
"type": "standalone",
"elements": [
{
"id": "string",
"prompt": "string",
"promptHidden": true,
"helperText": "string",
"type": "Text",
"required": true,
"propertyId": "string",
"propertyData": {
"type": "Text",
"objectType": "contact",
"status": "active"
},
"contactField": "firstName",
"placeholder": "string"
}
]
}
}export interface Response {
data:
| {
/**
* The form's ID.
*/
id: string;
/**
* The form's display name.
*/
name: string;
/**
* If true, the name of the form will not be shown to respondents.
*/
nameHidden?: boolean;
/**
* The ID of the host who owns this form.
*/
ownerId: string;
/**
* Determines the status of the form.
* - draft: the form cannot be accessed directly at its URL, and may not show up to the organizer in tables by default
* - active: the form can be accessed by its URL, and appears to the organizer in all tables
* - archived: for all intents and purposes, the form is deleted, but can still be accessed and restored in the forms dashboard
*/
status: "draft" | "active" | "archived";
/**
* A form's layout consists of rows, each with one or more columns. Each column
* contains a single form element. Form layouts determine the order that the
* form's elements are displayed in, not the order of the form's `elements`
* array.
*/
rows: {
/**
* Determines which elements are displayed in the row, and how much of the
* row's total width each element occupies.
*/
columns: {
/**
* The index of the element in the form's `elements` array which is
* displayed in this column.
*/
elementIndex: number;
/**
* A value between 0 and 1 that determines the width of this column in the row.
* The sum of all `widthFraction` values in a row always sums to 1.
*/
widthFraction: number;
}[];
}[];
/**
* Text displayed in the form's submission button. Typically, "Submit" is the default.
*/
submitButtonText: string;
/**
* Whether the form's submission button should shrink to fit its label ("auto"), or fill its container ("fill").
*/
submitButtonWidth: "auto" | "fill";
/**
* If `submitButtonWidth` is "auto", this determines how the submission button is horizontally aligned.
*/
submitButtonAlign?: "left" | "center";
type: "standalone";
/**
* Form questions (input fields) or static elements (text blocks, images, etc.)
*/
elements: (
| {
/**
* The unique ID of this element. Present on existing elements returned from the backend, omitted when creating new ones.
*/
id?: string;
/**
* For question elements, the question text; for static elements, a label shown above the element.
*/
prompt: string;
/**
* If true, the element's prompt will not be shown to respondents.
*/
promptHidden?: boolean;
/**
* Optional subtle helper text to display below the element.
*/
helperText?: string;
type: "Text";
/**
* If true, the respondent must answer this question to submit the form.
*/
required: boolean;
/**
* ID of a CRM property that will be set by the answer to this question.
* The CRM property's data type must align with the question's type.
* For standalone forms, only Contact properties can be used.
* For order forms, Ticket properties can be used for ticket-holder questions,
* Order properties can be used for buyer-only questions, and Contact properties
* can be used in either section.
*/
propertyId?: string;
/**
* If propertyId is specified, this will contain additional data about the CRM property linked to this question. Populated by the backend when fetching the form, not saved to the database.
*/
propertyData?: {
type: "Text";
/**
* The kind of object that a form-linked CRM property writes to.
* - contact: properties on customer contact records
* - order: properties on orders (buyer-level)
* - ticket: properties on individual products within an order
*/
objectType: "contact" | "order" | "ticket";
/**
* Determines where this property can be used. "archived" properties are
* soft-deleted (any existing reference to them remains valid) but only "active"
* properties should be used in new workflows, forms, etc.
*/
status: "active" | "archived";
};
/**
* Instead of setting a custom CRM property, text questions may set the
* built-in `firstName` and `lastName` fields on contacts.
* Questions may set a CRM property, a contact field, or neither; but not both.
*/
contactField?: "firstName" | "lastName";
/**
* Placeholder text to show when the input is empty.
*/
placeholder?: string;
}
| {
/**
* The unique ID of this element. Present on existing elements returned from the backend, omitted when creating new ones.
*/
id?: string;
/**
* For question elements, the question text; for static elements, a label shown above the element.
*/
prompt: string;
/**
* If true, the element's prompt will not be shown to respondents.
*/
promptHidden?: boolean;
/**
* Optional subtle helper text to display below the element.
*/
helperText?: string;
type: "Multi-line Text";
/**
* If true, the respondent must answer this question to submit the form.
*/
required: boolean;
/**
* ID of a CRM property that will be set by the answer to this question.
* The CRM property's data type must align with the question's type.
* For standalone forms, only Contact properties can be used.
* For order forms, Ticket properties can be used for ticket-holder questions,
* Order properties can be used for buyer-only questions, and Contact properties
* can be used in either section.
*/
propertyId?: string;
/**
* If propertyId is specified, this will contain additional data about the CRM property linked to this question. Populated by the backend when fetching the form, not saved to the database.
*/
propertyData?: {
type: "Multi-line Text";
/**
* The kind of object that a form-linked CRM property writes to.
* - contact: properties on customer contact records
* - order: properties on orders (buyer-level)
* - ticket: properties on individual products within an order
*/
objectType: "contact" | "order" | "ticket";
/**
* Determines where this property can be used. "archived" properties are
* soft-deleted (any existing reference to them remains valid) but only "active"
* properties should be used in new workflows, forms, etc.
*/
status: "active" | "archived";
};
/**
* Placeholder text to show when the input is empty.
*/
placeholder?: string;
}
| {
/**
* The unique ID of this element. Present on existing elements returned from the backend, omitted when creating new ones.
*/
id?: string;
/**
* For question elements, the question text; for static elements, a label shown above the element.
*/
prompt: string;
/**
* If true, the element's prompt will not be shown to respondents.
*/
promptHidden?: boolean;
/**
* Optional subtle helper text to display below the element.
*/
helperText?: string;
type: "Select One";
/**
* If true, the respondent must answer this question to submit the form.
*/
required: boolean;
/**
* If the question is not linked to a CRM property, this array will contain the question's options. If the question is linked to a CRM property, the options are derived from the CRM property, and this field will be undefined.
*/
options?: string[];
/**
* ID of a CRM property that will be set by the answer to this question.
* The CRM property's data type must align with the question's type.
* For standalone forms, only Contact properties can be used.
* For order forms, Ticket properties can be used for ticket-holder questions,
* Order properties can be used for buyer-only questions, and Contact properties
* can be used in either section.
* If specified, the property also provides the selectable options, and exactly
* one of `propertyId` or `options` must be specified.
*/
propertyId?: string;
/**
* If propertyId is specified, this will contain additional data about the CRM property linked to this question. Populated by the backend when fetching the form, not saved to the database. If a question is linked to a CRM property, its options are used instead of unique options being defined in the question.
*/
propertyData?: {
options: {
/**
* The value stored when this option is selected.
*/
value: string;
/**
* The display label for this option.
*/
label: string;
}[];
type: "Select One";
/**
* The kind of object that a form-linked CRM property writes to.
* - contact: properties on customer contact records
* - order: properties on orders (buyer-level)
* - ticket: properties on individual products within an order
*/
objectType: "contact" | "order" | "ticket";
/**
* Determines where this property can be used. "archived" properties are
* soft-deleted (any existing reference to them remains valid) but only "active"
* properties should be used in new workflows, forms, etc.
*/
status: "active" | "archived";
};
/**
* If true, renders as a dropdown list instead of radio buttons.
*/
dropdown?: boolean;
/**
* Only visible when `dropdown` is true.
*/
placeholder?: string;
/**
* Conditional logic groups that reveal other elements based on selected options
*/
logicGroups?: {
/**
* The index of the element in the form's `elements` array which is revealed
* when this logic group's condition is satisfied.
*/
revealedElementIndex: number;
/**
* The indices of the options in the question's `options` array, or its
* custom property's options. The way these options are used depends on the
* `operator` property.
* An index of -1 specifies the "Other" option, for applicable question types.
*/
optionIndices: number[];
/**
* The operator applied to the options specified by the `optionIndices` property
*/
operator: "all_of" | "any_of" | "none_of";
}[];
}
| {
/**
* The unique ID of this element. Present on existing elements returned from the backend, omitted when creating new ones.
*/
id?: string;
/**
* For question elements, the question text; for static elements, a label shown above the element.
*/
prompt: string;
/**
* If true, the element's prompt will not be shown to respondents.
*/
promptHidden?: boolean;
/**
* Optional subtle helper text to display below the element.
*/
helperText?: string;
type: 'Select One or "Other"';
/**
* If true, the respondent must answer this question to submit the form.
*/
required: boolean;
/**
* If the question is not linked to a CRM property, this array will contain the question's options. If the question is linked to a CRM property, the options are derived from the CRM property, and this field will be undefined.
*/
options?: string[];
/**
* ID of a CRM property that will be set by the answer to this question.
* The CRM property's data type must align with the question's type.
* For standalone forms, only Contact properties can be used.
* For order forms, Ticket properties can be used for ticket-holder questions,
* Order properties can be used for buyer-only questions, and Contact properties
* can be used in either section.
* If specified, the property also provides the selectable options, and exactly
* one of `propertyId` or `options` must be specified.
*/
propertyId?: string;
/**
* If propertyId is specified, this will contain additional data about the CRM property linked to this question. Populated by the backend when fetching the form, not saved to the database. If a question is linked to a CRM property, its options are used instead of unique options being defined in the question.
*/
propertyData?: {
options: {
/**
* The value stored when this option is selected.
*/
value: string;
/**
* The display label for this option.
*/
label: string;
}[];
type: "Select One";
/**
* The kind of object that a form-linked CRM property writes to.
* - contact: properties on customer contact records
* - order: properties on orders (buyer-level)
* - ticket: properties on individual products within an order
*/
objectType: "contact" | "order" | "ticket";
/**
* Determines where this property can be used. "archived" properties are
* soft-deleted (any existing reference to them remains valid) but only "active"
* properties should be used in new workflows, forms, etc.
*/
status: "active" | "archived";
};
/**
* The label for the freeform "Other" option.
*/
otherPrompt: string;
/**
* Conditional logic groups that reveal other elements based on selected options
*/
logicGroups?: {
/**
* The index of the element in the form's `elements` array which is revealed
* when this logic group's condition is satisfied.
*/
revealedElementIndex: number;
/**
* The indices of the options in the question's `options` array, or its
* custom property's options. The way these options are used depends on the
* `operator` property.
* An index of -1 specifies the "Other" option, for applicable question types.
*/
optionIndices: number[];
/**
* The operator applied to the options specified by the `optionIndices` property
*/
operator: "all_of" | "any_of" | "none_of";
}[];
}
| {
/**
* The unique ID of this element. Present on existing elements returned from the backend, omitted when creating new ones.
*/
id?: string;
/**
* For question elements, the question text; for static elements, a label shown above the element.
*/
prompt: string;
/**
* If true, the element's prompt will not be shown to respondents.
*/
promptHidden?: boolean;
/**
* Optional subtle helper text to display below the element.
*/
helperText?: string;
type: "Select Multiple";
/**
* If the question is not linked to a CRM property, this array will contain the question's options. If the question is linked to a CRM property, the options are derived from the CRM property, and this field will be undefined.
*/
options?: string[];
/**
* ID of a CRM property that will be set by the answer to this question.
* The CRM property's data type must align with the question's type.
* For standalone forms, only Contact properties can be used.
* For order forms, Ticket properties can be used for ticket-holder questions,
* Order properties can be used for buyer-only questions, and Contact properties
* can be used in either section.
* If specified, the property also provides the selectable options, and exactly
* one of `propertyId` or `options` must be specified.
*/
propertyId?: string;
/**
* If propertyId is specified, this will contain additional data about the CRM property linked to this question. Populated by the backend when fetching the form, not saved to the database. If a question is linked to a CRM property, its options are used instead of unique options being defined in the question.
*/
propertyData?: {
options: {
/**
* The value stored when this option is selected.
*/
value: string;
/**
* The display label for this option.
*/
label: string;
}[];
type: "Select Multiple";
/**
* The kind of object that a form-linked CRM property writes to.
* - contact: properties on customer contact records
* - order: properties on orders (buyer-level)
* - ticket: properties on individual products within an order
*/
objectType: "contact" | "order" | "ticket";
/**
* Determines where this property can be used. "archived" properties are
* soft-deleted (any existing reference to them remains valid) but only "active"
* properties should be used in new workflows, forms, etc.
*/
status: "active" | "archived";
};
/**
* Reserved for future use, must not be set to true
*/
dropdown?: false;
/**
* Minimum number of options that must be selected. Set to 0 to make the question optional.
*/
minChoices: number;
/**
* Maximum number of options that can be selected, or no limit if omitted
*/
maxChoices?: number;
/**
* Conditional logic groups that reveal other elements based on selected options
*/
logicGroups?: {
/**
* The index of the element in the form's `elements` array which is revealed
* when this logic group's condition is satisfied.
*/
revealedElementIndex: number;
/**
* The indices of the options in the question's `options` array, or its
* custom property's options. The way these options are used depends on the
* `operator` property.
* An index of -1 specifies the "Other" option, for applicable question types.
*/
optionIndices: number[];
/**
* The operator applied to the options specified by the `optionIndices` property
*/
operator: "all_of" | "any_of" | "none_of";
}[];
}
| {
/**
* The unique ID of this element. Present on existing elements returned from the backend, omitted when creating new ones.
*/
id?: string;
/**
* For question elements, the question text; for static elements, a label shown above the element.
*/
prompt: string;
/**
* If true, the element's prompt will not be shown to respondents.
*/
promptHidden?: boolean;
/**
* Optional subtle helper text to display below the element.
*/
helperText?: string;
type: 'Select Multiple with "Other"';
/**
* If the question is not linked to a CRM property, this array will contain the question's options. If the question is linked to a CRM property, the options are derived from the CRM property, and this field will be undefined.
*/
options?: string[];
/**
* ID of a CRM property that will be set by the answer to this question.
* The CRM property's data type must align with the question's type.
* For standalone forms, only Contact properties can be used.
* For order forms, Ticket properties can be used for ticket-holder questions,
* Order properties can be used for buyer-only questions, and Contact properties
* can be used in either section.
* If specified, the property also provides the selectable options, and exactly
* one of `propertyId` or `options` must be specified.
*/
propertyId?: string;
/**
* If propertyId is specified, this will contain additional data about the CRM property linked to this question. Populated by the backend when fetching the form, not saved to the database. If a question is linked to a CRM property, its options are used instead of unique options being defined in the question.
*/
propertyData?: {
options: {
/**
* The value stored when this option is selected.
*/
value: string;
/**
* The display label for this option.
*/
label: string;
}[];
type: "Select Multiple";
/**
* The kind of object that a form-linked CRM property writes to.
* - contact: properties on customer contact records
* - order: properties on orders (buyer-level)
* - ticket: properties on individual products within an order
*/
objectType: "contact" | "order" | "ticket";
/**
* Determines where this property can be used. "archived" properties are
* soft-deleted (any existing reference to them remains valid) but only "active"
* properties should be used in new workflows, forms, etc.
*/
status: "active" | "archived";
};
/**
* Minimum number of options that must be selected. Set to 0 to make the question optional.
*/
minChoices: number;
/**
* Maximum number of options that can be selected, or no limit if omitted
*/
maxChoices?: number;
/**
* The label for the freeform "Other" option.
*/
otherPrompt: string;
/**
* Conditional logic groups that reveal other elements based on selected options
*/
logicGroups?: {
/**
* The index of the element in the form's `elements` array which is revealed
* when this logic group's condition is satisfied.
*/
revealedElementIndex: number;
/**
* The indices of the options in the question's `options` array, or its
* custom property's options. The way these options are used depends on the
* `operator` property.
* An index of -1 specifies the "Other" option, for applicable question types.
*/
optionIndices: number[];
/**
* The operator applied to the options specified by the `optionIndices` property
*/
operator: "all_of" | "any_of" | "none_of";
}[];
}
| {
/**
* The unique ID of this element. Present on existing elements returned from the backend, omitted when creating new ones.
*/
id?: string;
/**
* For question elements, the question text; for static elements, a label shown above the element.
*/
prompt: string;
/**
* If true, the element's prompt will not be shown to respondents.
*/
promptHidden?: boolean;
/**
* Optional subtle helper text to display below the element.
*/
helperText?: string;
type: "Yes/No";
/**
* If true, the respondent must answer this question to submit the form.
*/
required: boolean;
/**
* ID of a CRM property that will be set by the answer to this question.
* The CRM property's data type must align with the question's type.
* For standalone forms, only Contact properties can be used.
* For order forms, Ticket properties can be used for ticket-holder questions,
* Order properties can be used for buyer-only questions, and Contact properties
* can be used in either section.
*/
propertyId?: string;
/**
* If propertyId is specified, this will contain additional data about the CRM property linked to this question. Populated by the backend when fetching the form, not saved to the database.
*/
propertyData?: {
type: "Yes/No";
/**
* The kind of object that a form-linked CRM property writes to.
* - contact: properties on customer contact records
* - order: properties on orders (buyer-level)
* - ticket: properties on individual products within an order
*/
objectType: "contact" | "order" | "ticket";
/**
* Determines where this property can be used. "archived" properties are
* soft-deleted (any existing reference to them remains valid) but only "active"
* properties should be used in new workflows, forms, etc.
*/
status: "active" | "archived";
};
/**
* Reserved for future use, must be set to true
*/
dropdown: true;
/**
* Instead of setting a custom CRM property, yes/no questions may set the
* built-in `status` fields on contacts, which represents whether the contact
* wants to receive communications from the host. The two values that can be
* set by a yes/no question are "opted-in" for "yes"/true, or "unsubscribed"
* for "no"/false.
* Questions may set a CRM property, a contact field, or neither; but not both.
*/
contactField?: "status";
/**
* Conditional logic groups that reveal other elements based on the yes/no value.
*/
logicGroups?: {
/**
* The index of the element in the form's `elements` array which is revealed
* when this logic group's condition is satisfied.
*/
revealedElementIndex: number;
/**
* Determines whether the question's value must be strictly equal to the logic
* group's `value` property, or not strictly equal to it. Note that
* `undefined` (no answer) is treated differently from an explicit `false`
* answer.
*/
selectionType: "is" | "is_not";
/**
* Determines the value which is compared to the form answer's value for this
* logic group (the type of comparison depends on the `selectionType` property).
*/
value: boolean;
}[];
/**
* If true, respondents must answer "Yes" to this question to submit their response.
*/
yesRequired?: boolean;
}
| {
/**
* The unique ID of this element. Present on existing elements returned from the backend, omitted when creating new ones.
*/
id?: string;
/**
* For question elements, the question text; for static elements, a label shown above the element.
*/
prompt: string;
/**
* If true, the element's prompt will not be shown to respondents.
*/
promptHidden?: boolean;
/**
* Optional subtle helper text to display below the element.
*/
helperText?: string;
type: "Date";
/**
* If true, the respondent must answer this question to submit the form.
*/
required: boolean;
/**
* Earliest selectable date in YYYY-MM-DD format
*/
min?: string;
/**
* Latest selectable date in YYYY-MM-DD format
*/
max?: string;
/**
* ID of a CRM property that will be set by the answer to this question.
* The CRM property's data type must align with the question's type.
* For standalone forms, only Contact properties can be used.
* For order forms, Ticket properties can be used for ticket-holder questions,
* Order properties can be used for buyer-only questions, and Contact properties
* can be used in either section.
*/
propertyId?: string;
/**
* If propertyId is specified, this will contain additional data about the CRM property linked to this question. Populated by the backend when fetching the form, not saved to the database.
*/
propertyData?: {
type: "Date";
/**
* The kind of object that a form-linked CRM property writes to.
* - contact: properties on customer contact records
* - order: properties on orders (buyer-level)
* - ticket: properties on individual products within an order
*/
objectType: "contact" | "order" | "ticket";
/**
* Determines where this property can be used. "archived" properties are
* soft-deleted (any existing reference to them remains valid) but only "active"
* properties should be used in new workflows, forms, etc.
*/
status: "active" | "archived";
};
}
| {
/**
* The unique ID of this element. Present on existing elements returned from the backend, omitted when creating new ones.
*/
id?: string;
/**
* For question elements, the question text; for static elements, a label shown above the element.
*/
prompt: string;
/**
* If true, the element's prompt will not be shown to respondents.
*/
promptHidden?: boolean;
/**
* Optional subtle helper text to display below the element.
*/
helperText?: string;
type: "File";
/**
* If true, the respondent must answer this question to submit the form.
*/
required: boolean;
/**
* File categories allowed to be uploaded. Must contain at least one element.
*
* @minItems 1
*/
accept: [
"images" | "documents" | "data" | "audio" | "video",
...("images" | "documents" | "data" | "audio" | "video")[]
];
/**
* ID of a CRM property that will be set by the answer to this question.
* The CRM property's data type must align with the question's type.
* For standalone forms, only Contact properties can be used.
* For order forms, Ticket properties can be used for ticket-holder questions,
* Order properties can be used for buyer-only questions, and Contact properties
* can be used in either section.
*/
propertyId?: string;
/**
* If propertyId is specified, this will contain additional data about the CRM property linked to this question. Populated by the backend when fetching the form, not saved to the database.
*/
propertyData?: {
type: "File";
/**
* The kind of object that a form-linked CRM property writes to.
* - contact: properties on customer contact records
* - order: properties on orders (buyer-level)
* - ticket: properties on individual products within an order
*/
objectType: "contact" | "order" | "ticket";
/**
* Determines where this property can be used. "archived" properties are
* soft-deleted (any existing reference to them remains valid) but only "active"
* properties should be used in new workflows, forms, etc.
*/
status: "active" | "archived";
};
}
| {
/**
* The unique ID of this element. Present on existing elements returned from the backend, omitted when creating new ones.
*/
id?: string;
/**
* For question elements, the question text; for static elements, a label shown above the element.
*/
prompt: string;
/**
* If true, the element's prompt will not be shown to respondents.
*/
promptHidden?: boolean;
/**
* Optional subtle helper text to display below the element.
*/
helperText?: string;
type: "Email";
/**
* If true, the respondent must answer this question to submit the form.
*/
required: boolean;
/**
* ID of a CRM property that will be set by the answer to this question.
* The CRM property's data type must align with the question's type.
* For standalone forms, only Contact properties can be used.
* For order forms, Ticket properties can be used for ticket-holder questions,
* Order properties can be used for buyer-only questions, and Contact properties
* can be used in either section.
*/
propertyId?: string;
/**
* If propertyId is specified, this will contain additional data about the CRM property linked to this question. Populated by the backend when fetching the form, not saved to the database.
*/
propertyData?: {
type: "Email";
/**
* The kind of object that a form-linked CRM property writes to.
* - contact: properties on customer contact records
* - order: properties on orders (buyer-level)
* - ticket: properties on individual products within an order
*/
objectType: "contact" | "order" | "ticket";
/**
* Determines where this property can be used. "archived" properties are
* soft-deleted (any existing reference to them remains valid) but only "active"
* properties should be used in new workflows, forms, etc.
*/
status: "active" | "archived";
};
/**
* Placeholder text to show when the input is empty.
*/
placeholder?: string;
/**
* Instead of setting a custom CRM property, email questions may set the
* built-in `email` field on contacts. A question which sets this contact
* field is required if any other questions in the form use a `contactField`
* or a Contact CRM property, since email is how contacts are identified.
* Questions may set a CRM property, a contact field, or neither; but not both.
*/
contactField?: "email";
}
| {
/**
* The unique ID of this element. Present on existing elements returned from the backend, omitted when creating new ones.
*/
id?: string;
/**
* For question elements, the question text; for static elements, a label shown above the element.
*/
prompt: string;
/**
* If true, the element's prompt will not be shown to respondents.
*/
promptHidden?: boolean;
/**
* Optional subtle helper text to display below the element.
*/
helperText?: string;
type: "Phone";
/**
* If true, the respondent must answer this question to submit the form.
*/
required: boolean;
/**
* ID of a CRM property that will be set by the answer to this question.
* The CRM property's data type must align with the question's type.
* For standalone forms, only Contact properties can be used.
* For order forms, Ticket properties can be used for ticket-holder questions,
* Order properties can be used for buyer-only questions, and Contact properties
* can be used in either section.
*/
propertyId?: string;
/**
* If propertyId is specified, this will contain additional data about the CRM property linked to this question. Populated by the backend when fetching the form, not saved to the database.
*/
propertyData?: {
type: "Phone";
/**
* The kind of object that a form-linked CRM property writes to.
* - contact: properties on customer contact records
* - order: properties on orders (buyer-level)
* - ticket: properties on individual products within an order
*/
objectType: "contact" | "order" | "ticket";
/**
* Determines where this property can be used. "archived" properties are
* soft-deleted (any existing reference to them remains valid) but only "active"
* properties should be used in new workflows, forms, etc.
*/
status: "active" | "archived";
};
/**
* Placeholder text to show when the input is empty.
*/
placeholder?: string;
/**
* Instead of setting a custom CRM property, phone questions may set the
* built-in `phone` field on contacts (i.e. the contact's phone number).
* Questions may set a CRM property, a contact field, or neither; but not both.
*/
contactField?: "phone";
}
| {
/**
* The unique ID of this element. Present on existing elements returned from the backend, omitted when creating new ones.
*/
id?: string;
/**
* For question elements, the question text; for static elements, a label shown above the element.
*/
prompt: string;
/**
* If true, the element's prompt will not be shown to respondents.
*/
promptHidden?: boolean;
/**
* Optional subtle helper text to display below the element.
*/
helperText?: string;
type: "Static Text";
/**
* The text content displayed in the block
*/
content: string;
}
| {
/**
* The unique ID of this element. Present on existing elements returned from the backend, omitted when creating new ones.
*/
id?: string;
/**
* For question elements, the question text; for static elements, a label shown above the element.
*/
prompt: string;
/**
* If true, the element's prompt will not be shown to respondents.
*/
promptHidden?: boolean;
/**
* Optional subtle helper text to display below the element.
*/
helperText?: string;
type: "Static Image";
/**
* URL of the image to display
*/
imageUrl: string;
/**
* Display width as a percentage of the container (1-100). Defaults to 100.
*/
imageWidth?: number;
}
)[];
}
| {
/**
* The form's ID.
*/
id: string;
/**
* The form's display name.
*/
name: string;
/**
* If true, the name of the form will not be shown to respondents.
*/
nameHidden?: boolean;
/**
* The ID of the host who owns this form.
*/
ownerId: string;
/**
* Determines the status of the form.
* - draft: the form cannot be accessed directly at its URL, and may not show up to the organizer in tables by default
* - active: the form can be accessed by its URL, and appears to the organizer in all tables
* - archived: for all intents and purposes, the form is deleted, but can still be accessed and restored in the forms dashboard
*/
status: "draft" | "active" | "archived";
/**
* A form's layout consists of rows, each with one or more columns. Each column
* contains a single form element. Form layouts determine the order that the
* form's elements are displayed in, not the order of the form's `elements`
* array.
*/
rows: {
/**
* Determines which elements are displayed in the row, and how much of the
* row's total width each element occupies.
*/
columns: {
/**
* The index of the element in the form's `elements` array which is
* displayed in this column.
*/
elementIndex: number;
/**
* A value between 0 and 1 that determines the width of this column in the row.
* The sum of all `widthFraction` values in a row always sums to 1.
*/
widthFraction: number;
}[];
}[];
/**
* Text displayed in the form's submission button. Typically, "Submit" is the default.
*/
submitButtonText: string;
/**
* Whether the form's submission button should shrink to fit its label ("auto"), or fill its container ("fill").
*/
submitButtonWidth: "auto" | "fill";
/**
* If `submitButtonWidth` is "auto", this determines how the submission button is horizontally aligned.
*/
submitButtonAlign?: "left" | "center";
type: "order";
/**
* Form questions (input fields) or static elements (text blocks, images, etc.)
*/
elements: (
| {
/**
* The unique ID of this element. Present on existing elements returned from the backend, omitted when creating new ones.
*/
id?: string;
/**
* For question elements, the question text; for static elements, a label shown above the element.
*/
prompt: string;
/**
* If true, the element's prompt will not be shown to respondents.
*/
promptHidden?: boolean;
/**
* Optional subtle helper text to display below the element.
*/
helperText?: string;
type: "Text";
/**
* If true, the respondent must answer this question to submit the form.
*/
required: boolean;
/**
* ID of a CRM property that will be set by the answer to this question.
* The CRM property's data type must align with the question's type.
* For standalone forms, only Contact properties can be used.
* For order forms, Ticket properties can be used for ticket-holder questions,
* Order properties can be used for buyer-only questions, and Contact properties
* can be used in either section.
*/
propertyId?: string;
/**
* If propertyId is specified, this will contain additional data about the CRM property linked to this question. Populated by the backend when fetching the form, not saved to the database.
*/
propertyData?: {
type: "Text";
/**
* The kind of object that a form-linked CRM property writes to.
* - contact: properties on customer contact records
* - order: properties on orders (buyer-level)
* - ticket: properties on individual products within an order
*/
objectType: "contact" | "order" | "ticket";
/**
* Determines where this property can be used. "archived" properties are
* soft-deleted (any existing reference to them remains valid) but only "active"
* properties should be used in new workflows, forms, etc.
*/
status: "active" | "archived";
};
/**
* Instead of setting a custom CRM property, text questions may set the
* built-in `firstName` and `lastName` fields on contacts.
* Questions may set a CRM property, a contact field, or neither; but not both.
*/
contactField?: "firstName" | "lastName";
/**
* Placeholder text to show when the input is empty.
*/
placeholder?: string;
/**
* For order forms only. Restricts this element to only appear when at least one
* of the referenced event items or products is in the cart. If present (even if
* empty), the element is hidden by default.
*/
forEventItems?: (
| {
type: "eventItem";
eventId: string;
itemId: string;
}
| {
type: "eventProduct";
eventId: string;
productId: string;
}
| {
type: "checkoutProduct";
/**
* The ID of the standalone checkout containing the product.
*/
checkoutId: string;
productId: string;
}
)[];
/**
* For order forms only. If true, the element must be in a row greater than or
* equal to `attendeeRowsStart`, and an instance of the element will appear for
* every ticket in the cart. Otherwise, the element must be in a row less than
* `attendeeRowsStart`, and only a single instance of the element will appear.
*/
askAllAttendees: boolean;
}
| {
/**
* The unique ID of this element. Present on existing elements returned from the backend, omitted when creating new ones.
*/
id?: string;
/**
* For question elements, the question text; for static elements, a label shown above the element.
*/
prompt: string;
/**
* If true, the element's prompt will not be shown to respondents.
*/
promptHidden?: boolean;
/**
* Optional subtle helper text to display below the element.
*/
helperText?: string;
type: "Multi-line Text";
/**
* If true, the respondent must answer this question to submit the form.
*/
required: boolean;
/**
* ID of a CRM property that will be set by the answer to this question.
* The CRM property's data type must align with the question's type.
* For standalone forms, only Contact properties can be used.
* For order forms, Ticket properties can be used for ticket-holder questions,
* Order properties can be used for buyer-only questions, and Contact properties
* can be used in either section.
*/
propertyId?: string;
/**
* If propertyId is specified, this will contain additional data about the CRM property linked to this question. Populated by the backend when fetching the form, not saved to the database.
*/
propertyData?: {
type: "Multi-line Text";
/**
* The kind of object that a form-linked CRM property writes to.
* - contact: properties on customer contact records
* - order: properties on orders (buyer-level)
* - ticket: properties on individual products within an order
*/
objectType: "contact" | "order" | "ticket";
/**
* Determines where this property can be used. "archived" properties are
* soft-deleted (any existing reference to them remains valid) but only "active"
* properties should be used in new workflows, forms, etc.
*/
status: "active" | "archived";
};
/**
* Placeholder text to show when the input is empty.
*/
placeholder?: string;
/**
* For order forms only. Restricts this element to only appear when at least one
* of the referenced event items or products is in the cart. If present (even if
* empty), the element is hidden by default.
*/
forEventItems?: (
| {
type: "eventItem";
eventId: string;
itemId: string;
}
| {
type: "eventProduct";
eventId: string;
productId: string;
}
| {
type: "checkoutProduct";
/**
* The ID of the standalone checkout containing the product.
*/
checkoutId: string;
productId: string;
}
)[];
/**
* For order forms only. If true, the element must be in a row greater than or
* equal to `attendeeRowsStart`, and an instance of the element will appear for
* every ticket in the cart. Otherwise, the element must be in a row less than
* `attendeeRowsStart`, and only a single instance of the element will appear.
*/
askAllAttendees: boolean;
}
| {
/**
* The unique ID of this element. Present on existing elements returned from the backend, omitted when creating new ones.
*/
id?: string;
/**
* For question elements, the question text; for static elements, a label shown above the element.
*/
prompt: string;
/**
* If true, the element's prompt will not be shown to respondents.
*/
promptHidden?: boolean;
/**
* Optional subtle helper text to display below the element.
*/
helperText?: string;
type: "Select One";
/**
* If true, the respondent must answer this question to submit the form.
*/
required: boolean;
/**
* If the question is not linked to a CRM property, this array will contain the question's options. If the question is linked to a CRM property, the options are derived from the CRM property, and this field will be undefined.
*/
options?: string[];
/**
* ID of a CRM property that will be set by the answer to this question.
* The CRM property's data type must align with the question's type.
* For standalone forms, only Contact properties can be used.
* For order forms, Ticket properties can be used for ticket-holder questions,
* Order properties can be used for buyer-only questions, and Contact properties
* can be used in either section.
* If specified, the property also provides the selectable options, and exactly
* one of `propertyId` or `options` must be specified.
*/
propertyId?: string;
/**
* If propertyId is specified, this will contain additional data about the CRM property linked to this question. Populated by the backend when fetching the form, not saved to the database. If a question is linked to a CRM property, its options are used instead of unique options being defined in the question.
*/
propertyData?: {
options: {
/**
* The value stored when this option is selected.
*/
value: string;
/**
* The display label for this option.
*/
label: string;
}[];
type: "Select One";
/**
* The kind of object that a form-linked CRM property writes to.
* - contact: properties on customer contact records
* - order: properties on orders (buyer-level)
* - ticket: properties on individual products within an order
*/
objectType: "contact" | "order" | "ticket";
/**
* Determines where this property can be used. "archived" properties are
* soft-deleted (any existing reference to them remains valid) but only "active"
* properties should be used in new workflows, forms, etc.
*/
status: "active" | "archived";
};
/**
* If true, renders as a dropdown list instead of radio buttons.
*/
dropdown?: boolean;
/**
* Only visible when `dropdown` is true.
*/
placeholder?: string;
/**
* Conditional logic groups that reveal other elements based on selected options
*/
logicGroups?: {
/**
* The index of the element in the form's `elements` array which is revealed
* when this logic group's condition is satisfied.
*/
revealedElementIndex: number;
/**
* The indices of the options in the question's `options` array, or its
* custom property's options. The way these options are used depends on the
* `operator` property.
* An index of -1 specifies the "Other" option, for applicable question types.
*/
optionIndices: number[];
/**
* The operator applied to the options specified by the `optionIndices` property
*/
operator: "all_of" | "any_of" | "none_of";
}[];
/**
* For order forms only. Restricts this element to only appear when at least one
* of the referenced event items or products is in the cart. If present (even if
* empty), the element is hidden by default.
*/
forEventItems?: (
| {
type: "eventItem";
eventId: string;
itemId: string;
}
| {
type: "eventProduct";
eventId: string;
productId: string;
}
| {
type: "checkoutProduct";
/**
* The ID of the standalone checkout containing the product.
*/
checkoutId: string;
productId: string;
}
)[];
/**
* For order forms only. If true, the element must be in a row greater than or
* equal to `attendeeRowsStart`, and an instance of the element will appear for
* every ticket in the cart. Otherwise, the element must be in a row less than
* `attendeeRowsStart`, and only a single instance of the element will appear.
*/
askAllAttendees: boolean;
}
| {
/**
* The unique ID of this element. Present on existing elements returned from the backend, omitted when creating new ones.
*/
id?: string;
/**
* For question elements, the question text; for static elements, a label shown above the element.
*/
prompt: string;
/**
* If true, the element's prompt will not be shown to respondents.
*/
promptHidden?: boolean;
/**
* Optional subtle helper text to display below the element.
*/
helperText?: string;
type: 'Select One or "Other"';
/**
* If true, the respondent must answer this question to submit the form.
*/
required: boolean;
/**
* If the question is not linked to a CRM property, this array will contain the question's options. If the question is linked to a CRM property, the options are derived from the CRM property, and this field will be undefined.
*/
options?: string[];
/**
* ID of a CRM property that will be set by the answer to this question.
* The CRM property's data type must align with the question's type.
* For standalone forms, only Contact properties can be used.
* For order forms, Ticket properties can be used for ticket-holder questions,
* Order properties can be used for buyer-only questions, and Contact properties
* can be used in either section.
* If specified, the property also provides the selectable options, and exactly
* one of `propertyId` or `options` must be specified.
*/
propertyId?: string;
/**
* If propertyId is specified, this will contain additional data about the CRM property linked to this question. Populated by the backend when fetching the form, not saved to the database. If a question is linked to a CRM property, its options are used instead of unique options being defined in the question.
*/
propertyData?: {
options: {
/**
* The value stored when this option is selected.
*/
value: string;
/**
* The display label for this option.
*/
label: string;
}[];
type: "Select One";
/**
* The kind of object that a form-linked CRM property writes to.
* - contact: properties on customer contact records
* - order: properties on orders (buyer-level)
* - ticket: properties on individual products within an order
*/
objectType: "contact" | "order" | "ticket";
/**
* Determines where this property can be used. "archived" properties are
* soft-deleted (any existing reference to them remains valid) but only "active"
* properties should be used in new workflows, forms, etc.
*/
status: "active" | "archived";
};
/**
* The label for the freeform "Other" option.
*/
otherPrompt: string;
/**
* Conditional logic groups that reveal other elements based on selected options
*/
logicGroups?: {
/**
* The index of the element in the form's `elements` array which is revealed
* when this logic group's condition is satisfied.
*/
revealedElementIndex: number;
/**
* The indices of the options in the question's `options` array, or its
* custom property's options. The way these options are used depends on the
* `operator` property.
* An index of -1 specifies the "Other" option, for applicable question types.
*/
optionIndices: number[];
/**
* The operator applied to the options specified by the `optionIndices` property
*/
operator: "all_of" | "any_of" | "none_of";
}[];
/**
* For order forms only. Restricts this element to only appear when at least one
* of the referenced event items or products is in the cart. If present (even if
* empty), the element is hidden by default.
*/
forEventItems?: (
| {
type: "eventItem";
eventId: string;
itemId: string;
}
| {
type: "eventProduct";
eventId: string;
productId: string;
}
| {
type: "checkoutProduct";
/**
* The ID of the standalone checkout containing the product.
*/
checkoutId: string;
productId: string;
}
)[];
/**
* For order forms only. If true, the element must be in a row greater than or
* equal to `attendeeRowsStart`, and an instance of the element will appear for
* every ticket in the cart. Otherwise, the element must be in a row less than
* `attendeeRowsStart`, and only a single instance of the element will appear.
*/
askAllAttendees: boolean;
}
| {
/**
* The unique ID of this element. Present on existing elements returned from the backend, omitted when creating new ones.
*/
id?: string;
/**
* For question elements, the question text; for static elements, a label shown above the element.
*/
prompt: string;
/**
* If true, the element's prompt will not be shown to respondents.
*/
promptHidden?: boolean;
/**
* Optional subtle helper text to display below the element.
*/
helperText?: string;
type: "Select Multiple";
/**
* If the question is not linked to a CRM property, this array will contain the question's options. If the question is linked to a CRM property, the options are derived from the CRM property, and this field will be undefined.
*/
options?: string[];
/**
* ID of a CRM property that will be set by the answer to this question.
* The CRM property's data type must align with the question's type.
* For standalone forms, only Contact properties can be used.
* For order forms, Ticket properties can be used for ticket-holder questions,
* Order properties can be used for buyer-only questions, and Contact properties
* can be used in either section.
* If specified, the property also provides the selectable options, and exactly
* one of `propertyId` or `options` must be specified.
*/
propertyId?: string;
/**
* If propertyId is specified, this will contain additional data about the CRM property linked to this question. Populated by the backend when fetching the form, not saved to the database. If a question is linked to a CRM property, its options are used instead of unique options being defined in the question.
*/
propertyData?: {
options: {
/**
* The value stored when this option is selected.
*/
value: string;
/**
* The display label for this option.
*/
label: string;
}[];
type: "Select Multiple";
/**
* The kind of object that a form-linked CRM property writes to.
* - contact: properties on customer contact records
* - order: properties on orders (buyer-level)
* - ticket: properties on individual products within an order
*/
objectType: "contact" | "order" | "ticket";
/**
* Determines where this property can be used. "archived" properties are
* soft-deleted (any existing reference to them remains valid) but only "active"
* properties should be used in new workflows, forms, etc.
*/
status: "active" | "archived";
};
/**
* Reserved for future use, must not be set to true
*/
dropdown?: false;
/**
* Minimum number of options that must be selected. Set to 0 to make the question optional.
*/
minChoices: number;
/**
* Maximum number of options that can be selected, or no limit if omitted
*/
maxChoices?: number;
/**
* Conditional logic groups that reveal other elements based on selected options
*/
logicGroups?: {
/**
* The index of the element in the form's `elements` array which is revealed
* when this logic group's condition is satisfied.
*/
revealedElementIndex: number;
/**
* The indices of the options in the question's `options` array, or its
* custom property's options. The way these options are used depends on the
* `operator` property.
* An index of -1 specifies the "Other" option, for applicable question types.
*/
optionIndices: number[];
/**
* The operator applied to the options specified by the `optionIndices` property
*/
operator: "all_of" | "any_of" | "none_of";
}[];
/**
* For order forms only. Restricts this element to only appear when at least one
* of the referenced event items or products is in the cart. If present (even if
* empty), the element is hidden by default.
*/
forEventItems?: (
| {
type: "eventItem";
eventId: string;
itemId: string;
}
| {
type: "eventProduct";
eventId: string;
productId: string;
}
| {
type: "checkoutProduct";
/**
* The ID of the standalone checkout containing the product.
*/
checkoutId: string;
productId: string;
}
)[];
/**
* For order forms only. If true, the element must be in a row greater than or
* equal to `attendeeRowsStart`, and an instance of the element will appear for
* every ticket in the cart. Otherwise, the element must be in a row less than
* `attendeeRowsStart`, and only a single instance of the element will appear.
*/
askAllAttendees: boolean;
}
| {
/**
* The unique ID of this element. Present on existing elements returned from the backend, omitted when creating new ones.
*/
id?: string;
/**
* For question elements, the question text; for static elements, a label shown above the element.
*/
prompt: string;
/**
* If true, the element's prompt will not be shown to respondents.
*/
promptHidden?: boolean;
/**
* Optional subtle helper text to display below the element.
*/
helperText?: string;
type: 'Select Multiple with "Other"';
/**
* If the question is not linked to a CRM property, this array will contain the question's options. If the question is linked to a CRM property, the options are derived from the CRM property, and this field will be undefined.
*/
options?: string[];
/**
* ID of a CRM property that will be set by the answer to this question.
* The CRM property's data type must align with the question's type.
* For standalone forms, only Contact properties can be used.
* For order forms, Ticket properties can be used for ticket-holder questions,
* Order properties can be used for buyer-only questions, and Contact properties
* can be used in either section.
* If specified, the property also provides the selectable options, and exactly
* one of `propertyId` or `options` must be specified.
*/
propertyId?: string;
/**
* If propertyId is specified, this will contain additional data about the CRM property linked to this question. Populated by the backend when fetching the form, not saved to the database. If a question is linked to a CRM property, its options are used instead of unique options being defined in the question.
*/
propertyData?: {
options: {
/**
* The value stored when this option is selected.
*/
value: string;
/**
* The display label for this option.
*/
label: string;
}[];
type: "Select Multiple";
/**
* The kind of object that a form-linked CRM property writes to.
* - contact: properties on customer contact records
* - order: properties on orders (buyer-level)
* - ticket: properties on individual products within an order
*/
objectType: "contact" | "order" | "ticket";
/**
* Determines where this property can be used. "archived" properties are
* soft-deleted (any existing reference to them remains valid) but only "active"
* properties should be used in new workflows, forms, etc.
*/
status: "active" | "archived";
};
/**
* Minimum number of options that must be selected. Set to 0 to make the question optional.
*/
minChoices: number;
/**
* Maximum number of options that can be selected, or no limit if omitted
*/
maxChoices?: number;
/**
* The label for the freeform "Other" option.
*/
otherPrompt: string;
/**
* Conditional logic groups that reveal other elements based on selected options
*/
logicGroups?: {
/**
* The index of the element in the form's `elements` array which is revealed
* when this logic group's condition is satisfied.
*/
revealedElementIndex: number;
/**
* The indices of the options in the question's `options` array, or its
* custom property's options. The way these options are used depends on the
* `operator` property.
* An index of -1 specifies the "Other" option, for applicable question types.
*/
optionIndices: number[];
/**
* The operator applied to the options specified by the `optionIndices` property
*/
operator: "all_of" | "any_of" | "none_of";
}[];
/**
* For order forms only. Restricts this element to only appear when at least one
* of the referenced event items or products is in the cart. If present (even if
* empty), the element is hidden by default.
*/
forEventItems?: (
| {
type: "eventItem";
eventId: string;
itemId: string;
}
| {
type: "eventProduct";
eventId: string;
productId: string;
}
| {
type: "checkoutProduct";
/**
* The ID of the standalone checkout containing the product.
*/
checkoutId: string;
productId: string;
}
)[];
/**
* For order forms only. If true, the element must be in a row greater than or
* equal to `attendeeRowsStart`, and an instance of the element will appear for
* every ticket in the cart. Otherwise, the element must be in a row less than
* `attendeeRowsStart`, and only a single instance of the element will appear.
*/
askAllAttendees: boolean;
}
| {
/**
* The unique ID of this element. Present on existing elements returned from the backend, omitted when creating new ones.
*/
id?: string;
/**
* For question elements, the question text; for static elements, a label shown above the element.
*/
prompt: string;
/**
* If true, the element's prompt will not be shown to respondents.
*/
promptHidden?: boolean;
/**
* Optional subtle helper text to display below the element.
*/
helperText?: string;
type: "Yes/No";
/**
* If true, the respondent must answer this question to submit the form.
*/
required: boolean;
/**
* ID of a CRM property that will be set by the answer to this question.
* The CRM property's data type must align with the question's type.
* For standalone forms, only Contact properties can be used.
* For order forms, Ticket properties can be used for ticket-holder questions,
* Order properties can be used for buyer-only questions, and Contact properties
* can be used in either section.
*/
propertyId?: string;
/**
* If propertyId is specified, this will contain additional data about the CRM property linked to this question. Populated by the backend when fetching the form, not saved to the database.
*/
propertyData?: {
type: "Yes/No";
/**
* The kind of object that a form-linked CRM property writes to.
* - contact: properties on customer contact records
* - order: properties on orders (buyer-level)
* - ticket: properties on individual products within an order
*/
objectType: "contact" | "order" | "ticket";
/**
* Determines where this property can be used. "archived" properties are
* soft-deleted (any existing reference to them remains valid) but only "active"
* properties should be used in new workflows, forms, etc.
*/
status: "active" | "archived";
};
/**
* Reserved for future use, must be set to true
*/
dropdown: true;
/**
* Instead of setting a custom CRM property, yes/no questions may set the
* built-in `status` fields on contacts, which represents whether the contact
* wants to receive communications from the host. The two values that can be
* set by a yes/no question are "opted-in" for "yes"/true, or "unsubscribed"
* for "no"/false.
* Questions may set a CRM property, a contact field, or neither; but not both.
*/
contactField?: "status";
/**
* Conditional logic groups that reveal other elements based on the yes/no value.
*/
logicGroups?: {
/**
* The index of the element in the form's `elements` array which is revealed
* when this logic group's condition is satisfied.
*/
revealedElementIndex: number;
/**
* Determines whether the question's value must be strictly equal to the logic
* group's `value` property, or not strictly equal to it. Note that
* `undefined` (no answer) is treated differently from an explicit `false`
* answer.
*/
selectionType: "is" | "is_not";
/**
* Determines the value which is compared to the form answer's value for this
* logic group (the type of comparison depends on the `selectionType` property).
*/
value: boolean;
}[];
/**
* If true, respondents must answer "Yes" to this question to submit their response.
*/
yesRequired?: boolean;
/**
* For order forms only. Restricts this element to only appear when at least one
* of the referenced event items or products is in the cart. If present (even if
* empty), the element is hidden by default.
*/
forEventItems?: (
| {
type: "eventItem";
eventId: string;
itemId: string;
}
| {
type: "eventProduct";
eventId: string;
productId: string;
}
| {
type: "checkoutProduct";
/**
* The ID of the standalone checkout containing the product.
*/
checkoutId: string;
productId: string;
}
)[];
/**
* For order forms only. If true, the element must be in a row greater than or
* equal to `attendeeRowsStart`, and an instance of the element will appear for
* every ticket in the cart. Otherwise, the element must be in a row less than
* `attendeeRowsStart`, and only a single instance of the element will appear.
*/
askAllAttendees: boolean;
}
| {
/**
* The unique ID of this element. Present on existing elements returned from the backend, omitted when creating new ones.
*/
id?: string;
/**
* For question elements, the question text; for static elements, a label shown above the element.
*/
prompt: string;
/**
* If true, the element's prompt will not be shown to respondents.
*/
promptHidden?: boolean;
/**
* Optional subtle helper text to display below the element.
*/
helperText?: string;
type: "Date";
/**
* If true, the respondent must answer this question to submit the form.
*/
required: boolean;
/**
* Earliest selectable date in YYYY-MM-DD format
*/
min?: string;
/**
* Latest selectable date in YYYY-MM-DD format
*/
max?: string;
/**
* ID of a CRM property that will be set by the answer to this question.
* The CRM property's data type must align with the question's type.
* For standalone forms, only Contact properties can be used.
* For order forms, Ticket properties can be used for ticket-holder questions,
* Order properties can be used for buyer-only questions, and Contact properties
* can be used in either section.
*/
propertyId?: string;
/**
* If propertyId is specified, this will contain additional data about the CRM property linked to this question. Populated by the backend when fetching the form, not saved to the database.
*/
propertyData?: {
type: "Date";
/**
* The kind of object that a form-linked CRM property writes to.
* - contact: properties on customer contact records
* - order: properties on orders (buyer-level)
* - ticket: properties on individual products within an order
*/
objectType: "contact" | "order" | "ticket";
/**
* Determines where this property can be used. "archived" properties are
* soft-deleted (any existing reference to them remains valid) but only "active"
* properties should be used in new workflows, forms, etc.
*/
status: "active" | "archived";
};
/**
* For order forms only. Restricts this element to only appear when at least one
* of the referenced event items or products is in the cart. If present (even if
* empty), the element is hidden by default.
*/
forEventItems?: (
| {
type: "eventItem";
eventId: string;
itemId: string;
}
| {
type: "eventProduct";
eventId: string;
productId: string;
}
| {
type: "checkoutProduct";
/**
* The ID of the standalone checkout containing the product.
*/
checkoutId: string;
productId: string;
}
)[];
/**
* For order forms only. If true, the element must be in a row greater than or
* equal to `attendeeRowsStart`, and an instance of the element will appear for
* every ticket in the cart. Otherwise, the element must be in a row less than
* `attendeeRowsStart`, and only a single instance of the element will appear.
*/
askAllAttendees: boolean;
}
| {
/**
* The unique ID of this element. Present on existing elements returned from the backend, omitted when creating new ones.
*/
id?: string;
/**
* For question elements, the question text; for static elements, a label shown above the element.
*/
prompt: string;
/**
* If true, the element's prompt will not be shown to respondents.
*/
promptHidden?: boolean;
/**
* Optional subtle helper text to display below the element.
*/
helperText?: string;
type: "File";
/**
* If true, the respondent must answer this question to submit the form.
*/
required: boolean;
/**
* File categories allowed to be uploaded. Must contain at least one element.
*
* @minItems 1
*/
accept: [
"images" | "documents" | "data" | "audio" | "video",
...("images" | "documents" | "data" | "audio" | "video")[]
];
/**
* ID of a CRM property that will be set by the answer to this question.
* The CRM property's data type must align with the question's type.
* For standalone forms, only Contact properties can be used.
* For order forms, Ticket properties can be used for ticket-holder questions,
* Order properties can be used for buyer-only questions, and Contact properties
* can be used in either section.
*/
propertyId?: string;
/**
* If propertyId is specified, this will contain additional data about the CRM property linked to this question. Populated by the backend when fetching the form, not saved to the database.
*/
propertyData?: {
type: "File";
/**
* The kind of object that a form-linked CRM property writes to.
* - contact: properties on customer contact records
* - order: properties on orders (buyer-level)
* - ticket: properties on individual products within an order
*/
objectType: "contact" | "order" | "ticket";
/**
* Determines where this property can be used. "archived" properties are
* soft-deleted (any existing reference to them remains valid) but only "active"
* properties should be used in new workflows, forms, etc.
*/
status: "active" | "archived";
};
/**
* For order forms only. Restricts this element to only appear when at least one
* of the referenced event items or products is in the cart. If present (even if
* empty), the element is hidden by default.
*/
forEventItems?: (
| {
type: "eventItem";
eventId: string;
itemId: string;
}
| {
type: "eventProduct";
eventId: string;
productId: string;
}
| {
type: "checkoutProduct";
/**
* The ID of the standalone checkout containing the product.
*/
checkoutId: string;
productId: string;
}
)[];
/**
* For order forms only. If true, the element must be in a row greater than or
* equal to `attendeeRowsStart`, and an instance of the element will appear for
* every ticket in the cart. Otherwise, the element must be in a row less than
* `attendeeRowsStart`, and only a single instance of the element will appear.
*/
askAllAttendees: boolean;
}
| {
/**
* The unique ID of this element. Present on existing elements returned from the backend, omitted when creating new ones.
*/
id?: string;
/**
* For question elements, the question text; for static elements, a label shown above the element.
*/
prompt: string;
/**
* If true, the element's prompt will not be shown to respondents.
*/
promptHidden?: boolean;
/**
* Optional subtle helper text to display below the element.
*/
helperText?: string;
type: "Email";
/**
* If true, the respondent must answer this question to submit the form.
*/
required: boolean;
/**
* ID of a CRM property that will be set by the answer to this question.
* The CRM property's data type must align with the question's type.
* For standalone forms, only Contact properties can be used.
* For order forms, Ticket properties can be used for ticket-holder questions,
* Order properties can be used for buyer-only questions, and Contact properties
* can be used in either section.
*/
propertyId?: string;
/**
* If propertyId is specified, this will contain additional data about the CRM property linked to this question. Populated by the backend when fetching the form, not saved to the database.
*/
propertyData?: {
type: "Email";
/**
* The kind of object that a form-linked CRM property writes to.
* - contact: properties on customer contact records
* - order: properties on orders (buyer-level)
* - ticket: properties on individual products within an order
*/
objectType: "contact" | "order" | "ticket";
/**
* Determines where this property can be used. "archived" properties are
* soft-deleted (any existing reference to them remains valid) but only "active"
* properties should be used in new workflows, forms, etc.
*/
status: "active" | "archived";
};
/**
* Placeholder text to show when the input is empty.
*/
placeholder?: string;
/**
* Instead of setting a custom CRM property, email questions may set the
* built-in `email` field on contacts. A question which sets this contact
* field is required if any other questions in the form use a `contactField`
* or a Contact CRM property, since email is how contacts are identified.
* Questions may set a CRM property, a contact field, or neither; but not both.
*/
contactField?: "email";
/**
* For order forms only. Restricts this element to only appear when at least one
* of the referenced event items or products is in the cart. If present (even if
* empty), the element is hidden by default.
*/
forEventItems?: (
| {
type: "eventItem";
eventId: string;
itemId: string;
}
| {
type: "eventProduct";
eventId: string;
productId: string;
}
| {
type: "checkoutProduct";
/**
* The ID of the standalone checkout containing the product.
*/
checkoutId: string;
productId: string;
}
)[];
/**
* For order forms only. If true, the element must be in a row greater than or
* equal to `attendeeRowsStart`, and an instance of the element will appear for
* every ticket in the cart. Otherwise, the element must be in a row less than
* `attendeeRowsStart`, and only a single instance of the element will appear.
*/
askAllAttendees: boolean;
}
| {
/**
* The unique ID of this element. Present on existing elements returned from the backend, omitted when creating new ones.
*/
id?: string;
/**
* For question elements, the question text; for static elements, a label shown above the element.
*/
prompt: string;
/**
* If true, the element's prompt will not be shown to respondents.
*/
promptHidden?: boolean;
/**
* Optional subtle helper text to display below the element.
*/
helperText?: string;
type: "Phone";
/**
* If true, the respondent must answer this question to submit the form.
*/
required: boolean;
/**
* ID of a CRM property that will be set by the answer to this question.
* The CRM property's data type must align with the question's type.
* For standalone forms, only Contact properties can be used.
* For order forms, Ticket properties can be used for ticket-holder questions,
* Order properties can be used for buyer-only questions, and Contact properties
* can be used in either section.
*/
propertyId?: string;
/**
* If propertyId is specified, this will contain additional data about the CRM property linked to this question. Populated by the backend when fetching the form, not saved to the database.
*/
propertyData?: {
type: "Phone";
/**
* The kind of object that a form-linked CRM property writes to.
* - contact: properties on customer contact records
* - order: properties on orders (buyer-level)
* - ticket: properties on individual products within an order
*/
objectType: "contact" | "order" | "ticket";
/**
* Determines where this property can be used. "archived" properties are
* soft-deleted (any existing reference to them remains valid) but only "active"
* properties should be used in new workflows, forms, etc.
*/
status: "active" | "archived";
};
/**
* Placeholder text to show when the input is empty.
*/
placeholder?: string;
/**
* Instead of setting a custom CRM property, phone questions may set the
* built-in `phone` field on contacts (i.e. the contact's phone number).
* Questions may set a CRM property, a contact field, or neither; but not both.
*/
contactField?: "phone";
/**
* For order forms only. Restricts this element to only appear when at least one
* of the referenced event items or products is in the cart. If present (even if
* empty), the element is hidden by default.
*/
forEventItems?: (
| {
type: "eventItem";
eventId: string;
itemId: string;
}
| {
type: "eventProduct";
eventId: string;
productId: string;
}
| {
type: "checkoutProduct";
/**
* The ID of the standalone checkout containing the product.
*/
checkoutId: string;
productId: string;
}
)[];
/**
* For order forms only. If true, the element must be in a row greater than or
* equal to `attendeeRowsStart`, and an instance of the element will appear for
* every ticket in the cart. Otherwise, the element must be in a row less than
* `attendeeRowsStart`, and only a single instance of the element will appear.
*/
askAllAttendees: boolean;
}
| {
/**
* The unique ID of this element. Present on existing elements returned from the backend, omitted when creating new ones.
*/
id?: string;
/**
* For question elements, the question text; for static elements, a label shown above the element.
*/
prompt: string;
/**
* If true, the element's prompt will not be shown to respondents.
*/
promptHidden?: boolean;
/**
* Optional subtle helper text to display below the element.
*/
helperText?: string;
type: "Static Text";
/**
* The text content displayed in the block
*/
content: string;
/**
* For order forms only. Restricts this element to only appear when at least one
* of the referenced event items or products is in the cart. If present (even if
* empty), the element is hidden by default.
*/
forEventItems?: (
| {
type: "eventItem";
eventId: string;
itemId: string;
}
| {
type: "eventProduct";
eventId: string;
productId: string;
}
| {
type: "checkoutProduct";
/**
* The ID of the standalone checkout containing the product.
*/
checkoutId: string;
productId: string;
}
)[];
/**
* For order forms only. If true, the element must be in a row greater than or
* equal to `attendeeRowsStart`, and an instance of the element will appear for
* every ticket in the cart. Otherwise, the element must be in a row less than
* `attendeeRowsStart`, and only a single instance of the element will appear.
*/
askAllAttendees: boolean;
}
| {
/**
* The unique ID of this element. Present on existing elements returned from the backend, omitted when creating new ones.
*/
id?: string;
/**
* For question elements, the question text; for static elements, a label shown above the element.
*/
prompt: string;
/**
* If true, the element's prompt will not be shown to respondents.
*/
promptHidden?: boolean;
/**
* Optional subtle helper text to display below the element.
*/
helperText?: string;
type: "Static Image";
/**
* URL of the image to display
*/
imageUrl: string;
/**
* Display width as a percentage of the container (1-100). Defaults to 100.
*/
imageWidth?: number;
/**
* For order forms only. Restricts this element to only appear when at least one
* of the referenced event items or products is in the cart. If present (even if
* empty), the element is hidden by default.
*/
forEventItems?: (
| {
type: "eventItem";
eventId: string;
itemId: string;
}
| {
type: "eventProduct";
eventId: string;
productId: string;
}
| {
type: "checkoutProduct";
/**
* The ID of the standalone checkout containing the product.
*/
checkoutId: string;
productId: string;
}
)[];
/**
* For order forms only. If true, the element must be in a row greater than or
* equal to `attendeeRowsStart`, and an instance of the element will appear for
* every ticket in the cart. Otherwise, the element must be in a row less than
* `attendeeRowsStart`, and only a single instance of the element will appear.
*/
askAllAttendees: boolean;
}
)[];
/**
* The index of the first row in the form's `rows` array which is in the
* "ticket-holder" section.
*/
attendeeRowsStart: number;
};
}
Edit Form Settings
Update form-level settings such as name, status, and submit button properties. Only the fields provided will be overwritten; omitted fields are left unchanged. The `isEventForm` flag cannot be modified after creation. To modify elements or layout, use the element-specific tools.
Add Form Element
Add a new element to a form. For order forms, the element is appended to the buyer section. Otherwise, it is appended to the end of the form. A layout row for the element is created automatically, and the form is saved after the element is added. The new element is returned.