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 "inner_collection". 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.

Collection Ref

collection_ref

A 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.

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