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 |
item_count | Number | The number of rows in the returned collection |
static_page_bindable | Boolean | Allows collection rows to be connected on static (non-dynamic) pages within the site. |
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. |
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 <strong>ipsum</strong> dolor <em>sit</em> 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 |