Component Types

This page is part of the Components resource. It documents the component type enum and the form_data structure for each type. When you create or update a component, the type field selects the kind of component, and form_data must match the structure described here for that type.

When to use this page

• You need the list of valid component type values (integer enum).
• You need the exact form_data shape for a given type (field names, types, and validation).
• You are building FORM (type 9) components and need the form builder structure for the built-in form.

---

Component type enum

Every component has a type (integer). The following values are supported:

Value	Name	Description
1	CONTENT	Rich text content
2	IMAGE_GALLERY	Image gallery with layout options
3	CONTENT_DETAILS	Contact / vCard-style details
4	SOCIAL_PROFILES	Social media profile links
5	VIDEOS	Video content
6	AUDIO	Audio content
7	LINKS	List of links
8	ITEM_LIST	Structured list of items
9	FORM	Form (built-in or external, e.g. Google Forms)
10	FILES	Downloadable files
11	EMBED	Custom HTML/JavaScript embed

Use the sections below for the form_data structure of each type. All form_data fields are validated; invalid or missing required fields result in a 422 validation error. File IDs in form_data must exist and be accessible to the authenticated user.

---

Type 1 — CONTENT

Rich text content shown on the page.

form_data

Field	Type	Required	Description
content	string	No	Rich text (HTML); max 65535 characters

Example

{
  "content": "<p>Rich text content here</p>"
}

---

Type 2 — IMAGE_GALLERY

Multiple images with a chosen layout.

form_data

Field	Type	Required	Description
image_file_ids	array (ULID)	Yes	Image file IDs (from Files)
layout	string	No	layout-1 (grid), layout-2 (masonry), layout-3 (carousel)

Example

{
  "image_file_ids": ["01arz3ndektsv4rrffq69g5fav", "01arz3ndektsv4rrffq69g5fav"],
  "layout": "layout-1"
}

---

Type 3 — CONTENT_DETAILS

Contact or vCard-style information (name, company, contact, address, etc.).

form_data

Field	Type	Required	Description
name_title	string	No	mr, mrs, ms, dr, prof, or empty
first_name	string	No	Max 50 characters
last_name	string	No	Max 50 characters
company_name	string	No	Max 255 characters
job_title	string	No	Max 100 characters
email	string	No	Valid email; max 255 characters
mobile	string	No	Max 20 characters
phone	string	No	Max 20 characters
fax	string	No	Max 20 characters
address	string	No	Max 255 characters
city	string	No	Max 100 characters
state	string	No	Max 100 characters
zip	string	No	Max 20 characters
country	string	No	Max 100 characters
website	string	No	Max 255 characters
summary	string	No	Max 5000 characters

Example

{
  "name_title": "mr",
  "first_name": "John",
  "last_name": "Doe",
  "company_name": "Acme Inc",
  "email": "[email protected]",
  "website": "https://example.com"
}

---

Type 4 — SOCIAL_PROFILES

Social media links with optional custom icons.

form_data

Field	Type	Required	Description
layout	string	No	layout-1 or layout-2
icon_type	string	No	icon or image
social_profiles	array	No	Up to 20 items. Each: platform, url, optional icon_file_id (ULID).

Example

{
  "layout": "layout-1",
  "icon_type": "icon",
  "social_profiles": [
    { "platform": "facebook", "url": "https://facebook.com/username" },
    { "platform": "twitter", "url": "https://twitter.com/username", "icon_file_id": "01arz3ndektsv4rrffq69g5fav" }
  ]
}

---

Type 5 — VIDEOS

Video content (one or more videos).

form_data

Field	Type	Required	Description
videos	array	No	Video objects. Each typically has video_file_id (ULID), title, description.

Example

{
  "videos": [
    {
      "video_file_id": "01arz3ndektsv4rrffq69g5fav",
      "title": "Video Title",
      "description": "Video description"
    }
  ]
}

---

Type 6 — AUDIO

Audio content (one or more audio items).

form_data

Field	Type	Required	Description
audio	array	No	Audio objects. Each typically has audio_file_id (ULID), title, description.

Example

{
  "audio": [
    {
      "audio_file_id": "01arz3ndektsv4rrffq69g5fav",
      "title": "Audio Title",
      "description": "Audio description"
    }
  ]
}

---

Type 7 — LINKS

A list of links (title, URL, optional description and image).

form_data

Field	Type	Required	Description
links	array	No	Link objects. Each: title, url; optional description, image_file_id (ULID).

Example

{
  "links": [
    {
      "title": "Link Title",
      "url": "https://example.com",
      "description": "Link description",
      "image_file_id": "01arz3ndektsv4rrffq69g5fav"
    }
  ]
}

---

Type 8 — ITEM_LIST

Structured list of items (title, description, optional image and link).

form_data

Field	Type	Required	Description
layout	string	No	layout-1 (1 col), layout-2 (2 col), layout-3 (list), layout-4 (carousel)
item_list	array	No	Item objects. Each: title, optional description, image_file_id (ULID), link.

Example

{
  "layout": "layout-1",
  "item_list": [
    {
      "title": "Item Title",
      "description": "Item description",
      "image_file_id": "01arz3ndektsv4rrffq69g5fav",
      "link": "https://example.com"
    }
  ]
}

---

Type 9 — FORM

Form block: either the built-in form builder (FreeQR) or an external form (e.g. Google Forms) embedded by URL.

form_data (top-level)

Field	Type	Required	Description
platform	string	No	built_in (FreeQR) or google_forms. Default: built_in.
url	string	No	External form URL (max 1024 characters). Used when platform is google_forms.
height	integer	No	Embed height in pixels (250–5000). Default: 500.
form_builder	object	No	Required when platform is built_in. Defines fields and behavior. See Form builder structure below.

Example (external form)

{
  "platform": "google_forms",
  "url": "https://docs.google.com/forms/d/e/.../viewform",
  "height": 500
}

Example (built-in form)

{
  "platform": "built_in",
  "height": 500,
  "form_builder": {
    "type": "default",
    "inputs": [
      { "type": "text", "name": "full_name", "label": "Full Name" },
      { "type": "textarea", "name": "message", "label": "Message" }
    ]
  }
}

Submissions from built-in forms are sent to the Form Submissions API; you can list and manage them per page.

Form builder structure

When platform is built_in, form_builder must be a valid form definition object.

Root object

Field	Type	Required	Description
type	string	Yes	Must be "default".
inputs	array	Yes	List of form fields; max 20 items. See Input objects (in this page).
metadata	object	No	Arbitrary key-value metadata; max 20 keys.

Constraints

• Serialized size of form_builder (JSON) must be at most 10 KB.
• form_builder must not be an empty object when provided.

Input objects

Each element of inputs is an object with:

Required (all input types)

Field	Type	Description
type	string	One of: text, textarea, radio, hidden, color, image, file, files.
name	string	Field name (1–100 characters). Used as the key in submission data. Must not contain *, [, or ].
label	string	Label shown to the user (1–100 characters).

Optional (all input types)

Field	Type	Description
description	string	Help text.
value	string/number	Pre-filled value.
default_value	string/number	Default value.
optional	boolean	If true, field is not required.
rules	array	Validation rules (e.g. ["required", "min:3", "max:255"]).
metadata	object	Arbitrary metadata; max 20 keys.

Optional for radio

Field	Type	Description
options	array	List of { "value": "…", "label": "…" }.

Allowed input types (form builder)

Type	Description
text	Single-line text.
textarea	Multi-line text.
radio	Single choice from options.
hidden	Hidden field.
color	Color (format: Color formats).
image	Single image file (file ID).
file	Single file upload (file ID).
files	Multiple file uploads (array of file IDs; max 20).

Example: minimal form_builder

{
  "type": "default",
  "inputs": [
    { "type": "text", "name": "email", "label": "Email" },
    { "type": "textarea", "name": "message", "label": "Message" }
  ]
}

Example: with radio and validation

{
  "type": "default",
  "inputs": [
    {
      "type": "text",
      "name": "full_name",
      "label": "Full Name",
      "rules": ["required", "min:2", "max:100"]
    },
    {
      "type": "radio",
      "name": "contact_preference",
      "label": "Contact preference",
      "options": [
        { "value": "email", "label": "Email" },
        { "value": "phone", "label": "Phone" }
      ]
    },
    {
      "type": "textarea",
      "name": "notes",
      "label": "Notes",
      "optional": true
    }
  ]
}

Submission payloads to POST https://v1.freeqr.io/api/form_submissions use keys in data that match each input name (e.g. full_name, contact_preference, notes).

---

Type 10 — FILES

Downloadable files (by file ID).

form_data

Field	Type	Required	Description
file_ids	array (ULID)	Yes	File IDs from the Files API.

Example

{
  "file_ids": ["01arz3ndektsv4rrffq69g5fav", "01arz3ndektsv4rrffq69g5fav"]
}

---

Type 11 — EMBED

Custom HTML or JavaScript (e.g. iframe, script).

form_data

Field	Type	Required	Description
code	string	No	HTML/JavaScript; max 65535 characters.

Example

{
  "code": "<iframe src=\"https://example.com\"></iframe>"
}

---

Using form_data in requests

When creating or updating a component, send a type and a matching form_data object. Example for an image gallery:

{
  "type": 2,
  "title": "My Gallery",
  "form_data": {
    "image_file_ids": ["01arz3ndektsv4rrffq69g5fav"],
    "layout": "layout-1"
  }
}

• Validation: form_data is validated per type; invalid or missing required fields return 422.
• File IDs: Any file ID in form_data must exist and be accessible to the authenticated user.
• Nested structures: Types like SOCIAL_PROFILES, VIDEOS, and FORM (with form_builder) have their own nested validation; see the sections above for details.

See the main Components page for the full list of endpoints (list, create, get, update, delete, bulk store, bulk update).