Core Concepts

Formium provides a powerful structure for working with forms and data. We understand that everyone has their own way of describing forms, so we want to introduce you to the terminology we've developed.

This guide will walk you through the core concepts and entities on our platform, as well as their relation to each other. Formium is an API-first platform, meaning every entity described below can be accessed with an API endpoint.

Form

Forms are a list of submissions, an API endpoint, and a set of form fields. We refer to this set of fields as a "schema."

Every form on Formium is publicly available at a unique URL formium.io. In addition, form schemas can be fetched through our API and then rendered natively into your application or website using our SDKs.

Field

A field is an element of a form (like a question).

There are multiple field types in Formium. The basic fields are Short Answer, Long Text, Radio, Checkboxes, Email, and URL.

All fields have a title and an optional description and type.

Fields have few shared options such as its initial visibility, whether it is required or not, its default value, etc. Some fields may also have special options that are relevant only to that kind of field.

Note: Fields may have "child" fields. For example, all the options of a Checkboxes field are also technically Choice fields.

Keys

Each field also has an administrative key that is used to represent the answer to it in each submission with your form as well as CSV exports and API integrations.

When you add a field to a form in the Formium Dashboard, Formium will attempt to generate this key for you once you're done typing the question title. When you change a question key, do it with caution, as new submissions with an answer to that question will use the new key, but old submissions will remain as they were with old one. When you create workflows (described later), a field's value will be available as template variables under {{values.<key>}}. But more on that later...

Submission

A submission is an individual response to a form.

Submissions can be created through our API or when someone fills out the version of your hosted form on formium.io.

Submissions are plain ol' objects. Their keys will most often match 1:1 with the field keys of your form, but they do not strictly have to. Submissions can actually contain arbitrary JSON data (as long as you stay within the limits). The reason for this relaxed approach to data is so that you can send both structured and unstructered data to Formium to suit your needs. For example, if your form is rendered behind a paywall in your app and you want want to dump some contextual data into the submission, you can just do it.

Workflows

Workflows allow you to automatically trigger tasks and processes in response to events on the platform such as new submissions, form schema updates, and form deletions.

Common use cases of workflows include:

• Posting submission data to Slack
• Sending an email "thank you" auto-responder
• Redeploying a website with a webhook

Formium includes common workflows out of the box while also allowing you to create custom webhooks to suit your needs. Our Email workflow will even let you send from your own email address or custom SMTP server. We also have a Zapier integration which allows you to further extend Formium using over 2000+ apps and services.

User

A user is anyone with a Formium account. Users can either be invited to an existing project (and customer), or sign up individually. If a user has signed up individually, a new project (and customer) is automatically created.

In any case, an existing user can always create additional projects or be invited to other existing projects.

Project

A project is a collection of forms, submissions, and workflows. Users belong to projects as either members or administrators.

• Forms: Comprise of a schema and a place to list submissions. All members of a project can view and edit forms.
• Submissions: Individual responses to a form. They trigger workflows when they are created.
• Workflows: A process or event triggered by a new submission or form update. A single workflow can be re-used/and assigned to multiple forms within a project.
• Logs: Recorded HTTP and SMTP request and response logs of workflows

Customer

A customer is a billing entity (i.e. a credit card). Project belongs to exactly one customer. Although the underlying data structure exists, at the moment, a customer and a project have a 1:1 relationship for non-enterprise accounts in the UI. However, for enterprise accounts, a customer can have multiple projects (1:many). Billing usage is aggregated across all projects owned by the customer.