Collection Object

A collection is a flexible data store (similar to a database), containing fields and values.
The collection API allows the structure of the collection and the data stored within to be created, retrieved, updated, and deleted.

Collection Properties

Property	Type	Description
name	String	The name of the returned collection
customer_lock	String	Lock state for customer editing. One of 'unlocked', 'structure_locked' or 'locked'. 'Unlocked' gives access to edit data and the structure (fields) of a collection, 'structure_locked' only allows the editing of data (values), and 'view_only' will limit access to both structure (fields) and data (values)
fields	Array	An array of objects containing the name and type of each field in the collection. See Field Properties table below
values	Array	An array of all data rows in the collection. See Value Properties table below
external_details	Object	Only available on external collections. Contains properties related to the data source. See External Detail Properties table below

📘
Lock states for collections
Image collections can only be set to the 'locked' or 'unlocked' states. Structural changes are never available to image collections. Similarly, external collections can only be set to the 'structure_locked' or 'unlocked' states as external collections will always receive their values from an external endpoint.

Field Properties

Property	Type	Description
name	String	The name of the field when it was created. Note: Use a URL friendly string.
type	String	The type of date within the field. See Collection Field Types table
inner_collection_fields	Array	Only available if the field type is "innercollection". An array of field properties within the inner collection. _Note: inner collections can only be nested one level deep

Value Properties

Property	Type	Description
id	Int	The unique number of the row within the collection. This is used if you need to update the row later.
data	Object	An object containing key-value pairs of the column name along with the data for that row.

External Detail Properties

Property	Type	Description
enabled	Bool	Whether this collection is enabled as external.
external_endpoint	String	An absolute URI containing the data within the collection. Note: external collections will not have a 'values' property containing actual data. These values are only available from the external endpoint.

Collection Field Types

Name (Editor UI)	Type (API )	Description
Plain Text	plain_text	Simple string of content you want to be displayed on the website in some form. This text cannot contain escaped HTML. The maximum length of this field is 2000 characters.
Rich Text	rich_text	Simple string of content you want to be displayed on the website in some form. This text can contain escaped HTML. The maximum length of this field is 2000 characters.
Image	image	Absolute URL pointing to a publicly available image resource. Externally hosted images will not benefit from automatic image resizing or optimization. To take advantage of these features, first upload the image and then provide the URL of the returned image.
Link	link	String in URL format. A value with a type of link is automatically available for various widgets
Number	number	Whole or decimal number represented with or without commas for thousands and using periods for decimals.
Date & Time	date_time	A compatible ISO date format. (See value examples below)
Business Hours	business_hours	Array of objects describing the hours of operation for a business.
Location	location	Object describing a business location.
Video	video	Absolute URL pointing to a publicly available Youtube, Vimeo, or DailyMotion video.
Email	email	A valid email address.
Phone	phone	A valid phone number.
Social Accounts	social_accounts	An object containing key/value combinations of social network names and a specific account identifier.
Inner Collection	collection	An array of objects containing a name and type property. Inner collections can include all field types except collection and collection_ref.

Example data type values

When providing data to a collection via an external endpoint, values must be provided in a format appropriate for the field type.

{
  "about_us": "Lorum ipsum dolor sit amet."
}

{
	"about_us": "Lorum &lt;strong&gt;ipsum&lt;/strong&gt; dolor &lt;em&gt;sit&lt;/em&gt; amet."
}

{
  "logo": "https://example.org/path/to/logo.png"
}

{
  "profile": "https://www.crunchbase.com/organization/duda"
}

{
  "price": 19.99
}

{
  "created_on": "2000-10-31T01:30:00",
  "updated_on": "2000-10-31T01:30",
  "last_viewed": "2000-10-30",
  "last_vote": "-0100-07-12T15:03:44"
}

[
  {
    "days":[
      "MON",
      "TUE",
      "WED",
      "THU",
      "FRI"
    ],
    "open":"9:00",
    "close":"18:00"
  }, {
    "days": [
      "SAT"
    ],
    "open": "12:00",
    "close": "16:00"
  }
]

{
  "address_geolocation":"123 15th St, Columbus, IN, United States",
  "geo":{
    "longitude":"-85.8938199",
    "latitude":"39.2157605"
  },
  "address":{
    "streetAddress":"123 15th St, Columbus, IN, United States"
  }
}

{
  "promo_vid": "https://vimeo.com/362415796"
}

{
  email: "[email protected]"
}

{
  phone: "+1 (123) 456-7890"
}

"social_accounts": {
  "email":"[email protected]",
  "whatsapp":"9543543543",
  "facebook":"duda",
  "twitter":"duda",
  "instagram":"duda",
  "youtube":"UCPMwzOc1Su-s2z-J1xiU9ig",
  "linkedin":"duda",
  "yelp":"orens-hummus-shop-palo-alto",
  "pinterest":"michelleobama",
  "google_my_business":"Cafe+Nona/@32.0718045,34.7809687,15z/data=!4m19!1m13!4m12!1m4!2m2!1d34.8127232!2d32.0503808!4e1!1m6!1m2!1s0x151d4b8468d5803f:0xc4b3f0a57332f82f!2z16DXldeg15Qg16rXnCDXkNeR15nXkeKArQ!2m2!1d34.7815956!2d32.0769206!3m4!1s0x151d4b8468d5803f:0xc4b3f0a57332f82f!8m2!3d32.0769206!4d34.7815956",
  "waze":"34.784267763974256, 32.07510593016749",
  "vimeo":"dudamobile",
  "snapchat":"michelleobama",
  "reddit":"duda",
  "tripadvisor":"Restaurant_Review-g32849-d2394400-Reviews-Oren_s_Hummus_Shop-Palo_Alto_California.html",
  "foursquare":"v/anita-la-mamma-del-gelato-%D7%90%D7%A0%D7%99%D7%98%D7%94/4b488bfff964a520184f26e3",
  "rss":"https://www.duda.co/blog/feed/",
}

"all_photos": [
  {
    "alt": "Lorum ipsum",
    "url": "https://example.org/path/to/image.png
  },{
    "alt": "dolor sit amet",
    "url": "https://example.org/path/to/another.png"
  }
]

Example field creation payloads

When creating new fields in a collection, either through the create collection or create field endpoints, you must always supply a name and a valid data type. (See the Collection Field Types table above.) Inner collection and collection reference field types must also provide an array of their nested fields.

{
  "name": "my-inner-collection",
  "type": "collection",
  "inner_collection_fields": [
    {
      "name":"title",
      "type":"text"
    },{
      "name":"description",
      "type":"text"
    }
  ]
}

{
    "name": "my-field",
    "type": "<TYPE>"
}

Data formatters

Some data types allow you to input a formatter. Applying a formatter allows you to visually output the value in a specified pattern, while keeping the original available for functionality such as filtering or sorting. Formatters can be specified in the Collection Fields screen of the collection UI.

Date & Time Formatter

The following ISO formats can be supplied as date & time values from an external endpoint.

"-0100-07-12T15:03:44",
"2000-10-31T01:30:00",
"2000-10-31T01:30",
"2000-10-30",
"01:30"

The following characters are available to format valid date & time values.

Formatter	Meaning	Output
G	era	AD; Anno Domini; A
u	year	2004; 04
y	year-of-era	2004; 04
D	day-of-year	189
M/L	month-of-year	7; 07; Jul; July; J
d	day-of-month	10
Q/q	quarter-of-year	3; 03; Q3; 3rd quarter
Y	week-based-year	1996; 96
W	week-of-month	4
E	day-of-week	Tue; Tuesday; T
e/c	localized day-of-week	2; 02; Tue; Tuesday; T
F	week-of-month	3
a	am-pm-of-day	PM
h	clock-hour-of-am-pm (1-12)	12
K	hour-of-am-pm (0-11)	0
k	clock-hour-of-am-pm (1-24)	0
H	hour-of-day (0-23)	0
m	minute-of-hour	30
s	second-of-minute	55
S	fraction-of-second	978
A	milli-of-day	1234
n	nano-of-second	987654321
N	nano-of-day	1234000000
V	time-zone ID	America/Los_Angeles; Z; -08:30
z	time-zone name	Pacific Standard Time; PST
O	localized zone-offset	GMT+8; GMT+08:00; UTC-08:00;
X	zone-offset 'Z' for zero	Z; -08; -0830; -08:30; -083015; -08:30:15;
x	zone-offset	+0000; -08; -0830; -08:30; -083015; -08:30:15;
Z	zone-offset	+0000; -0800; -08:00;

Examples

Data	Formatter	Output
2000-10-31T01:30:00	YYYY-MM-dd	2000-10-31
2000-10-31T01:30:00	MMM, dd, YY	Oct, 03, 21
2000-10-31T01:30:00	HH:mm:SS	01:30:00
2000-10-31T01:30:00	E, MMMM dd - HH:mm	Tue, October 31 - 01:30

Collection Properties

📘Lock states for collections

Field Properties

Value Properties

External Detail Properties

Collection Field Types

Example data type values

Example field creation payloads

Data formatters

Date & Time Formatter

Examples

📘
Lock states for collections