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

PropertyTypeDescription
nameStringThe name of the returned collection
customer_lockStringLock 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)
fieldsArrayAn array of objects containing the name and type of each field in the collection. See Field Properties table below
valuesArrayAn array of all data rows in the collection. See Value Properties table below
external_detailsObjectOnly 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

PropertyTypeDescription
nameStringThe name of the field when it was created. Note: Use a URL friendly string.
typeStringThe type of date within the field. See Collection Field Types table
inner_collection_fieldsArrayOnly available if the field type is "inner_collection". An array of field properties within the inner collection. Note: inner collections can only be nested one level deep

Value Properties

PropertyTypeDescription
idIntThe unique number of the row within the collection. This is used if you need to update the row later.
dataObjectAn object containing key-value pairs of the column name along with the data for that row.

External Detail Properties

PropertyTypeDescription
enabledBoolWhether this collection is enabled as external.
external_endpointStringAn 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 Textplain_textSimple 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 Textrich_textSimple 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.
ImageimageAbsolute 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.
LinklinkString in URL format. A value with a type of link is automatically available for various widgets
NumbernumberWhole or decimal number represented with or without commas for thousands and using periods for decimals.
Date & Timedate_timeA compatible ISO date format. (See value examples below)
Business Hoursbusiness_hoursArray of objects describing the hours of operation for a business.
LocationlocationObject describing a business location.
VideovideoAbsolute URL pointing to a publicly available Youtube, Vimeo, or DailyMotion video.
EmailemailA valid email address.
PhonephoneA valid phone number.
Social Accountssocial_accountsAn object containing key/value combinations of social network names and a specific account identifier.
Inner CollectioncollectionAn array of objects containing a name and type property. Inner collections can include all field types except collection and collection_ref.
Collection Refcollection_refA string referencing another collection connected to the same site.

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"
  }
]
{
  "related": "Collection Name"
}

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-source-collection",
    "type": "collection_ref",
    "inner_collection_fields": [
        {
            "name":"title",
            "type":"text"
        },{
            "name":"description",
            "type":"text"
        }
    ]
}
{
  "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.

FormatterMeaningOutput
GeraAD; Anno Domini; A
uyear2004; 04
yyear-of-era2004; 04
Dday-of-year189
M/Lmonth-of-year7; 07; Jul; July; J
dday-of-month10
Q/qquarter-of-year3; 03; Q3; 3rd quarter
Yweek-based-year1996; 96
Wweek-of-month4
Eday-of-weekTue; Tuesday; T
e/clocalized day-of-week2; 02; Tue; Tuesday; T
Fweek-of-month3
aam-pm-of-dayPM
hclock-hour-of-am-pm (1-12)12
Khour-of-am-pm (0-11)0
kclock-hour-of-am-pm (1-24)0
Hhour-of-day (0-23)0
mminute-of-hour30
ssecond-of-minute55
Sfraction-of-second978
Amilli-of-day1234
nnano-of-second987654321
Nnano-of-day1234000000
Vtime-zone IDAmerica/Los_Angeles; Z; -08:30
ztime-zone namePacific Standard Time; PST
Olocalized zone-offsetGMT+8; GMT+08:00; UTC-08:00;
Xzone-offset 'Z' for zeroZ; -08; -0830; -08:30; -083015; -08:30:15;
xzone-offset+0000; -08; -0830; -08:30; -083015; -08:30:15;
Zzone-offset+0000; -0800; -08:00;

Examples

DataFormatterOutput
2000-10-31T01:30:00YYYY-MM-dd2000-10-31
2000-10-31T01:30:00MMM, dd, YYOct, 03, 21
2000-10-31T01:30:00HH:mm:SS01:30:00
2000-10-31T01:30:00E, MMMM dd - HH:mmTue, October 31 - 01:30