Zenfolio Objects


The ultimate object of interest is a photograph, which is represented by the photo object in the Zenfolio object model. The photo object contains all the information associated with the photograph: dimensions, title and caption, keywords and categories, EXIF metadata, etc.

Each photo has a number of display images representing it. One of them is the original image file with several additional image sizes generated for Web display. These images are not part of the photo object. Instead, the photo object contains URLs of where these image sizes can be found.

Videos are also represented by photo objects. All the photo properties, including display images, are applicable to videos as well. In addition, videos have their own distinct properties such as duration and playback URL.


Photo objects can be combined into photosets, which come in two flavors: galleries and collections. Galleries are physical containers for photographs: every photo object is contained within one and only one gallery. Collections contain links to photographs. A photo can be a member of any number of collections (including zero). Despite this difference, galleries and collections are very similar in other aspects, so both are represented as photoset objects in the object model.

Similar to photographs, photosets can be assigned a title, caption, keywords, and categories. A photoset title does not have to be unique but it cannot be empty.

Photoset Groups

Photoset objects are further combined into photoset groups. Photoset groups can contain not only photosets but also other photoset groups thus forming a tree-like hierarchical structure. At the top of the hierarchy is the user's root photoset group.

Photoset groups can be assigned a title and a caption, but not keywords and categories. Group title does not have to be unique but it cannot be empty.

Photos, photosets, and photoset groups all contain a reference to the access descriptor object that describes the access control settings applied to the object. See Access Control for more information on the access descriptor object.


A Zenfolio user account is represented by the user object. This object contains a reference to the user's root photoset group as well as the user profile information. The user profile information consists of two parts: private profile and public profile. The private profile is accessible only to the account owner. Information in the private profile is only used by Zenfolio to deliver service-related messages. On the other hand, the public profile is accessible to anyone. This is what Zenfolio members want to tell about themselves to their visitors.

User File

The user file object represents a generic file associated with a user account and includes a URL from which it can be downloaded. Unlike photo objects, user file objects are not access-controlled, they are accessible to everyone.

Photos, user files, photosets, and photoset groups are identified by a unique numeric ID. Each object type has its own identifier space; for example, a photo and a photoset can have the same ID value. User objects are identified by the account login name, which is known as user name in the user interface.

Gallery File

The gallery file object represents a Raw file uploaded to a gallery. Gallery files can be of any type, but unlike user files they are associated with a specific gallery and are subject to access control. Gallery files can be linked to specific photos in the same gallery to establish logical correspondence between the photo and the gallery file.

Messages and Mailboxes

Every photo, photoset, or a photoset group has a mailbox associated with it. A mailbox is a collection of messages added by visitors or the photographer. Messages in the photo mailbox are called comments, while messages in the photoset and photoset group mailboxes are called guestbook entries, although both are treated identically in the API.