Components

Components are the building blocks of a page. Each component has a type (e.g. text content, image gallery, form, links) and type-specific form data that defines its content and options. Components belong to a page and are scoped by page template (e.g. LINK, VCARD_PLUS) so different templates can show different component sets.

In this section

• Endpoints (this page): list, create, get, update, delete, and bulk operations for components.
• Component types: full reference for the type enum and the form_data structure for each type. Use it when building request bodies for create/update.

All component endpoints require authentication unless noted otherwise.

---

List Components

Get a list of all components for a page.

GET https://v1.freeqr.io/api/pages/{page}/components

Requires Authentication: Yes

Path Parameters

Parameter	Type	Required	Description
page	string (ULID)	Yes	Page ID

Query Parameters

Parameter	Type	Required	Description
page	integer	No	Page number (default: 1)
limit	integer	No	Items per page (default: 10, max: 100)
filters	object	No	Filter object (see Filters section below)

Filters

Filters allow you to narrow down the results based on specific criteria. Filters are passed as a query parameter object:

GET https://v1.freeqr.io/api/pages/{page}/components?filters[page_template]=0

page_template

The page_template filter acts as a scope that isolates components into separate sets. Each page template maintains its own independent collection of components, meaning components created for one template are completely separate from components in other templates.

For example:

• Components created with page_template=1 (LINK) are isolated from components with page_template=2 (VCARD_PLUS)
• Each template scope can have its own set of components with their own sorting, visibility, and form data
• When you query components, you must specify the page_template filter to access components within that specific scope

Default Behavior:

• If the page_template filter is not provided, the API will automatically use the page's template as the default scope
• If the page doesn't have a template set, it falls back to DEFAULT (0)
• If an invalid page_template value is provided, it will also use the page's template (or DEFAULT if the page has no template)

Value	Template	Description
0	DEFAULT	Default template (fallback if page has no template)
1	LINK	Link template
2	VCARD_PLUS	vCard Plus template
3	DOCUMENT	Document template
4	SOCIAL	Social template
5	IMAGES	Images template
6	VIDEOS	Videos template
7	AUDIO	Audio template
8	PRODUCTS	Products template
9	BUSINESS	Business template
10	EVENT	Event template
11	COUPON	Coupon template
12	FEEDBACK	Feedback template

Note: If the specified template doesn't have components yet, default components will be automatically created for that template scope.

Example Request with Filter

curl -X GET "https://v1.freeqr.io/api/pages/{page}/components?filters[page_template]=1" \
  -H "Authorization: Bearer your-api-key-here"

Response

{
  "data": [
    {
      "id": "01arz3ndektsv4rrffq69g5fav",
      "type": 1,
      "title": "My Component",
      "description": "Component description",
      "visibility": 1,
      "sorting": 0,
      "created_at": "2024-01-01T00:00:00.000000Z",
      "updated_at": "2024-01-01T00:00:00.000000Z"
    }
  ],
  "meta": {
    "total": 1
  },
  "included_files": []
}

Create Component

Create a new component for a page.

POST https://v1.freeqr.io/api/pages/{page}/components

Requires Authentication: Yes

Path Parameters

Parameter	Type	Required	Description
page	string (ULID)	Yes	Page ID

Request Body

{
  "type": 1,
  "page_template": 0,
  "visibility": 1,
  "show_header": true,
  "wrap_content": true,
  "title": "My Component",
  "description": "Component description",
  "form_data": {
    "content": "Rich text content here"
  },
  "sorting": 0
}

Note: The form_data structure depends on the component type. See Component types for the full reference.

Parameters

Parameter	Type	Required	Description
type	integer	Yes	Component type (1–11). See Component types for the enum and form_data for each type.
page_template	integer	No	Page template enum: 0 (DEFAULT), 1 (LINK), 2 (VCARD_PLUS), etc.
visibility	integer	No	Visibility level enum: 1 (PUBLIC), 2 (HIDDEN), 3 (PRIVATE)
show_header	boolean	No	Whether to show header
wrap_content	boolean	No	Whether to wrap content
title	string	No	Component title (max 100 characters)
description	string	No	Component description (max 255 characters)
form_data	object	No	Component form data. Structure depends on type. See Component types for type-specific structures.
sorting	integer	No	Sort order (0-1000000)

Response

{
  "data": {
    "id": "01arz3ndektsv4rrffq69g5fav",
    "type": 1,
    "title": "My Component",
    "description": "Component description",
    "visibility": 1,
    "sorting": 0,
    "created_at": "2024-01-01T00:00:00.000000Z",
    "updated_at": "2024-01-01T00:00:00.000000Z"
  }
}

Bulk Store Components

Create multiple components at once.

POST https://v1.freeqr.io/api/pages/{page}/components:bulk_store

Requires Authentication: Yes

Path Parameters

Parameter	Type	Required	Description
page	string (ULID)	Yes	Page ID

Request Body

{
  "components": [
    {
      "type": 1,
      "title": "Component 1",
      "form_data": {},
      "sorting": 0
    },
    {
      "type": 2,
      "title": "Component 2",
      "form_data": {},
      "sorting": 1
    }
  ]
}

Parameters

Parameter	Type	Required	Description
components	array	Yes	Array of component objects (max 20 items)

Each component object uses the same parameters as Create Component.

Response

{
  "data": [
    {
      "id": "01arz3ndektsv4rrffq69g5fav",
      "type": 1,
      "title": "Component 1",
      "sorting": 0,
      "created_at": "2024-01-01T00:00:00.000000Z",
      "updated_at": "2024-01-01T00:00:00.000000Z"
    },
    {
      "id": "01arz3ndektsv4rrffq69g5fav",
      "type": 2,
      "title": "Component 2",
      "sorting": 1,
      "created_at": "2024-01-01T00:00:00.000000Z",
      "updated_at": "2024-01-01T00:00:00.000000Z"
    }
  ]
}

Bulk Update Components

Update multiple components at once.

POST https://v1.freeqr.io/api/pages/{page}/components:bulk_update

Requires Authentication: Yes

Path Parameters

Parameter	Type	Required	Description
page	string (ULID)	Yes	Page ID

Request Body

{
  "components": [
    {
      "id": "01arz3ndektsv4rrffq69g5fav",
      "title": "Updated Component 1",
      "sorting": 0
    },
    {
      "id": "01arz3ndektsv4rrffq69g5fav",
      "title": "Updated Component 2",
      "sorting": 1
    }
  ]
}

Parameters

Parameter	Type	Required	Description
components	array	Yes	Array of component objects with id and fields to update

Response

{
  "data": [
    {
      "id": "01arz3ndektsv4rrffq69g5fav",
      "type": 1,
      "title": "Updated Component 1",
      "sorting": 0,
      "created_at": "2024-01-01T00:00:00.000000Z",
      "updated_at": "2024-01-01T00:00:00.000000Z"
    },
    {
      "id": "01arz3ndektsv4rrffq69g5fav",
      "type": 2,
      "title": "Updated Component 2",
      "sorting": 1,
      "created_at": "2024-01-01T00:00:00.000000Z",
      "updated_at": "2024-01-01T00:00:00.000000Z"
    }
  ]
}

Get Component

Get a specific component by ID.

GET https://v1.freeqr.io/api/components/{id}

Requires Authentication: Yes

Path Parameters

Parameter	Type	Required	Description
id	string (ULID)	Yes	Component ID

Response

{
  "data": {
    "id": "01arz3ndektsv4rrffq69g5fav",
    "type": 1,
    "title": "My Component",
    "description": "Component description",
    "visibility": 1,
    "sorting": 0,
    "created_at": "2024-01-01T00:00:00.000000Z",
    "updated_at": "2024-01-01T00:00:00.000000Z"
  }
}

Update Component

Update an existing component.

PATCH https://v1.freeqr.io/api/components/{id}

Requires Authentication: Yes

Path Parameters

Parameter	Type	Required	Description
id	string (ULID)	Yes	Component ID

Request Body

Same parameters as Create Component, but all fields are optional.

Response

{
  "data": {
    "id": "01arz3ndektsv4rrffq69g5fav",
    "type": 1,
    "title": "Updated Component",
    "description": "Updated description",
    "visibility": 1,
    "sorting": 1,
    "created_at": "2024-01-01T00:00:00.000000Z",
    "updated_at": "2024-01-01T00:00:00.000000Z"
  }
}

Delete Component

Delete a component.

DELETE https://v1.freeqr.io/api/components/{id}

Requires Authentication: Yes

Path Parameters

Parameter	Type	Required	Description
id	string (ULID)	Yes	Component ID

Response

Returns the deleted component resource (same structure as Get Component).

---

See also

• Component types — Full reference for the type enum and form_data structure for each type.
• Pages — Components belong to pages; create and manage pages first.
• Files — Many component types reference file IDs (images, videos, audio, etc.) from the Files API.