Property elements

Elements describe what a property physically contains: its rooms and areas, and the appliances and fixtures inside them. They come in three layers. Categories are the organization’s taxonomy (bedroom, kitchen, dishwasher). Catalog entries are reusable make/model templates filed under a category, such as one TV model you install across many units. Property elements (element instances) are the actual things on one property, arranged as a tree of areas with items nested under them. Task checklists and repair tasks point at property elements. This guide covers the nine element operations and the three that manage element attachments. Every field is listed on the operation’s page in the API Reference.

Operation	Request	Permission
listElementCategories	GET /element-categories	view_properties
listElementCatalog	GET /element-catalog	view_properties
createElementCatalogEntry	POST /element-catalog	modify_properties
updateElementCatalogEntry	PATCH /element-catalog/{id}	modify_properties
deleteElementCatalogEntry	DELETE /element-catalog/{id}	modify_properties
listPropertyElements	GET /property-elements	view_properties
createPropertyElement	POST /property-elements	modify_properties
updatePropertyElement	PATCH /property-elements/{id}	modify_properties
deletePropertyElement	DELETE /property-elements/{id}	modify_properties
listElementAttachments	GET /element-attachments	view_properties
createElementAttachment	POST /element-attachments	modify_properties
deleteElementAttachment	DELETE /element-attachments/{id}	modify_properties

Paths are relative to your region’s base URL, for example https://api-us.suiteop.com/api/v1. See Authentication for permissions.

Catalog entries and property elements can be deleted permanently. The API has no read-one operation (the lists already return every field), and no way to create, rename or delete a category.

Categories

GET /element-categories takes no parameters and returns every category as one unpaginated array, areas first and then items, each sorted by name. Retired categories are included.

curl "https://api-us.suiteop.com/api/v1/element-categories" \
  -H "Authorization: Bearer sk_live_your_key_here"

{
  "data": [
    {
      "id": "3c9a1f7e-2b4d-4e8a-9f10-5a6b7c8d9e01",
      "name": "kitchen",
      "level": "area",
      "icon": null,
      "isSystem": true,
      "parentCategoryId": null,
      "archived": false
    },
    {
      "id": "8e2d4b6a-1c3f-4a5b-8d7e-9f0a1b2c3d4e",
      "name": "dishwasher",
      "level": "item",
      "icon": null,
      "isSystem": true,
      "parentCategoryId": null,
      "archived": false
    }
  ],
  "meta": { "requestId": "3f1c9a52-…" }
}

• Every organization is seeded with a fixed set of system categories (isSystem: true). Their name is a snake_case key such as living_room or half_bathroom, not a display label. Custom categories added in the app carry the name as it was typed.
• Category ids are generated per organization, so the same kitchen has a different id in every organization. This operation is the only way to get one, and both create operations below require it. Look ids up by name and level rather than hard-coding them.
• archived: true marks a retired category. It is listed so the categoryId an existing element still carries resolves, but it takes no new elements: creating an element in it, or moving one onto it, returns 400 validation_error. Pick categories with archived: false.
• Only area and item categories are returned. The legacy sub_item level is retired.

Catalog entries

A catalog entry is a template, not something placed anywhere. Linking a property element to it is optional.

Listing the catalog

GET /element-catalog returns every entry as one unpaginated array, sorted by name. Pass categoryId to narrow it to one category.

curl "https://api-us.suiteop.com/api/v1/element-catalog?categoryId=8e2d4b6a-1c3f-4a5b-8d7e-9f0a1b2c3d4e" \
  -H "Authorization: Bearer sk_live_your_key_here"

Each entry carries id, name, description, categoryId, make, model, sleepingCapacity, notes and metadata.

Creating an entry

POST /element-catalog requires name (up to 200 characters) and categoryId. The response is 201 with the new entry under data.

curl -X POST https://api-us.suiteop.com/api/v1/element-catalog \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Idempotency-Key: 6f1d2c3b-4a5e-4f60-8a7b-9c0d1e2f3a4b" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bosch 300 Series dishwasher",
    "categoryId": "8e2d4b6a-1c3f-4a5b-8d7e-9f0a1b2c3d4e",
    "make": "Bosch",
    "model": "SHE53C85N",
    "notes": "Clean the filter monthly.",
    "metadata": { "warrantyYears": 2 }
  }'

• name must be unique within its category for the organization. A duplicate returns 409 conflict_error, so read listElementCatalog before retrying a create. The same name in a different category is fine.
• categoryId must be an item category: a catalog entry is a product, so an area category returns 400 validation_error. One from another organization returns 404 not_found_error.
• description (up to 2,000 characters), make and model (up to 200 each), notes (up to 5,000) and metadata (a flat JSON object) are optional.
• sleepingCapacity (an integer, 0 or more) is how many people this type of element sleeps, for example 2 for a queen bed. Placed elements linked to the entry inherit it unless they override it. It is accepted only for categories with the built-in Sleeping capacity field (beds, sofa beds, bunk beds and cribs); for any other category it returns 400 validation_error. It reads back as null for those other categories.
• The name, description and notes you send are translated into the organization’s other languages automatically after the create.

Updating an entry

PATCH /element-catalog/{id} takes a data object with any of name, description, categoryId, make, model, sleepingCapacity, notes and metadata. Send null to clear any of them except name and categoryId.

curl -X PATCH https://api-us.suiteop.com/api/v1/element-catalog/5b7c9d1e-2f3a-4b5c-8d6e-7f8091a2b3c4 \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"data": {"model": "SHE53C85N-2", "notes": null}}'

• categoryId re-files the entry under another category at the same level. A category at a different level returns 400 validation_error.
• A rename onto a name its category already holds returns 409 conflict_error.
• metadata replaces the whole stored object. Merge on your side before sending it.
• Resending a text field unchanged doesn’t re-translate it. Only text that actually changes is re-translated, which replaces the other languages’ copies of that field.

Deleting a catalog entry

DELETE /element-catalog/{id} deletes the entry permanently and returns {"success": true}. Property elements linked to it stay where they are, with catalogEntryId cleared. The attachments the entry owns, such as manuals and photos, are deleted with it, so those elements stop showing them. There is no undo: read the entry with listElementCatalog first if you may need to recreate it.

Property elements

The tree

A property’s elements form a two-level tree:

• area: a room or zone, such as a kitchen, a bedroom or the pool. Areas are the roots and never have a parent. An area can carry a labelId saying which kind of its category it is, for example Outdoor for a pool; it is null on items.
• item: something inside an area, such as a dishwasher or a smoke alarm. Every item has exactly one area as its parent, on the same property.

A third level, sub_item, has been retired. It can’t be created, and existing sub-items were converted into supply lines on their parent area or item. The tree can still show a legacy one under its item’s childInstances, so read that array rather than assuming it is empty.

A new property starts with one area per bedroom and full bathroom it was created with, a half_bathroom area for a half bath, and any areas picked when it was created. Each room is its own area. Organizations whose system arrival, completion and general area categories are still live (archived: false) also get one of each of those. Where they are retired, they were replaced by task sections, and new properties get one only while a live template group still targets that category or an item inside it.

Listing a property’s elements

GET /property-elements?propertyId=… returns the property’s areas as an unpaginated array. Each area nests its items under childInstances. Each item also carries a childInstances array, which is empty unless the item still has a legacy sub_item.

curl "https://api-us.suiteop.com/api/v1/property-elements?propertyId=9a3d7e40-5b6c-4d7e-8f90-1a2b3c4d5e6f" \
  -H "Authorization: Bearer sk_live_your_key_here"

{
  "data": [
    {
      "id": "0d4e6f80-1a2b-4c3d-9e4f-5a6b7c8d9e0f",
      "name": "Kitchen",
      "level": "area",
      "categoryId": "3c9a1f7e-2b4d-4e8a-9f10-5a6b7c8d9e01",
      "labelId": null,
      "catalogEntryId": null,
      "propertyId": "9a3d7e40-5b6c-4d7e-8f90-1a2b3c4d5e6f",
      "parentInstanceId": null,
      "quantity": 1,
      "sleepingCapacity": null,
      "serialNumber": null,
      "make": null,
      "model": null,
      "description": null,
      "notes": null,
      "lastServicedAt": null,
      "warrantyExpiresAt": null,
      "metadata": null,
      "condition": null,
      "childInstances": [
        {
          "id": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
          "name": "Dishwasher",
          "level": "item",
          "categoryId": "8e2d4b6a-1c3f-4a5b-8d7e-9f0a1b2c3d4e",
          "labelId": null,
          "catalogEntryId": "5b7c9d1e-2f3a-4b5c-8d6e-7f8091a2b3c4",
          "propertyId": "9a3d7e40-5b6c-4d7e-8f90-1a2b3c4d5e6f",
          "parentInstanceId": "0d4e6f80-1a2b-4c3d-9e4f-5a6b7c8d9e0f",
          "quantity": 1,
          "sleepingCapacity": null,
          "serialNumber": "FD9601234567",
          "make": "Bosch",
          "model": "SHE53C85N",
          "description": null,
          "notes": null,
          "lastServicedAt": "2026-06-01T00:00:00.000Z",
          "warrantyExpiresAt": "2027-06-01T00:00:00.000Z",
          "metadata": null,
          "condition": {
            "result": "flag",
            "answerLabel": "Worn",
            "checkedAt": "2026-09-28T14:05:00.000Z"
          },
          "childInstances": []
        }
      ]
    }
  ],
  "meta": { "requestId": "3f1c9a52-…" }
}

• condition is the element’s newest condition check from a task: its result (pass, flag, fail or na, typed as an open string), the answerLabel in your language when there is a translation, and checkedAt; result and answerLabel may each be null. It is null when the element has never been checked, and when the caller holds neither view_tasks nor modify_tasks. Create and update responses always return null. An answer list with logsElementCondition on records its answers as checks; see Answer lists.
• Order is display order: siblings appear in the order they were created. There is no reorder operation.
• An unknown property, one in another organization, or one outside an OAuth token’s property access returns an empty array, not 404. An empty result doesn’t prove the property exists.
• Only elements filed on the property itself are listed. Elements an organization shares at the property-group level don’t appear here, and the API has no operation that lists them.
• level is typed as an open string so a future level can still be read. Handle values other than area and item.

Creating an element

POST /property-elements requires name, categoryId, level and propertyId. The reference marks propertyId optional, but a create without it is rejected with 400 validation_error. The response is 201 with the new element under data, without childInstances. Create an area first, then its items:

# 1. The area
curl -X POST https://api-us.suiteop.com/api/v1/property-elements \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Idempotency-Key: 2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c6d" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kitchen",
    "level": "area",
    "categoryId": "3c9a1f7e-2b4d-4e8a-9f10-5a6b7c8d9e01",
    "propertyId": "9a3d7e40-5b6c-4d7e-8f90-1a2b3c4d5e6f"
  }'

# 2. An item in it, using the area's data.id as parentInstanceId
curl -X POST https://api-us.suiteop.com/api/v1/property-elements \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Idempotency-Key: 3b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d7e" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dishwasher",
    "level": "item",
    "categoryId": "8e2d4b6a-1c3f-4a5b-8d7e-9f0a1b2c3d4e",
    "propertyId": "9a3d7e40-5b6c-4d7e-8f90-1a2b3c4d5e6f",
    "parentInstanceId": "0d4e6f80-1a2b-4c3d-9e4f-5a6b7c8d9e0f",
    "catalogEntryId": "5b7c9d1e-2f3a-4b5c-8d6e-7f8091a2b3c4",
    "make": "Bosch",
    "model": "SHE53C85N",
    "serialNumber": "FD9601234567"
  }'

• level is area or item. sub_item is rejected with 400 validation_error.
• categoryId must be a live category (archived: false); a retired one returns 400 validation_error.
• parentInstanceId is required for an item and must be an area; leave it out for an area. An item without a parent, an area with one, or an item under another item returns 400 validation_error. A parent that doesn’t exist or that you can’t reach returns 404 not_found_error first.
• propertyId is required for areas and items alike. For an item it must be the same property as its parent area, or the create returns 400 validation_error.
• groupId appears in the schema but is rejected with 400 validation_error. This operation places elements on a property only.
• catalogEntryId only links the template. make, model, notes and the other text fields are not copied from it, so send them yourself if you want them on the element. sleepingCapacity is the exception: see below.
• labelId is for areas only; on an item it returns 400 validation_error. It must be a label of the area’s own category. The API has no operation that lists labels: reuse a labelId that listPropertyElements returns on an existing area of that category.
• quantity: leave it out. Each physical thing is its own element, so a pair of nightstands is two createPropertyElement calls. The field is still accepted only so older SuiteOp apps keep working, and it’s being removed. If you send it, it creates that many separate elements and returns only the first: read the others’ ids with listPropertyElements. The copies of an area are named <name> 2 to <name> N, the copies of an item keep the name, and no copy gets the serialNumber or notes. Every element reads back with quantity: 1.
• sleepingCapacity overrides the catalog entry’s value for this placement. Omit it to inherit. As on catalog entries, it’s accepted only for categories with the built-in Sleeping capacity field, and returns 400 validation_error for any other.
• A categoryId, catalogEntryId, propertyId or parentInstanceId from another organization returns 404 not_found_error, and so does a property outside an OAuth token’s property access.
• The name, description and notes you send are translated into the organization’s other languages automatically.

Updating an element

PATCH /property-elements/{id} takes a data object with any of name, description, categoryId, labelId, catalogEntryId, sleepingCapacity, serialNumber, make, model, lastServicedAt, warrantyExpiresAt, notes and metadata. Send null to clear any of them except name and categoryId.

curl -X PATCH https://api-us.suiteop.com/api/v1/property-elements/7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"data": {"lastServicedAt": "2026-09-15T00:00:00Z", "notes": "Replaced drain pump."}}'

• categoryId re-files the element under another category at the same level: a room can’t become furniture. A category at a different level, or a retired one, returns 400 validation_error. Re-filing clears the element’s labelId unless you send a label of the new category in the same call.
• An element can’t be moved to another property or parent, and its level can’t change. Those fields are rejected with 400 validation_error. To move something, create a new element where it belongs.
• quantity is still accepted for older clients but ignored. To add more of something, create one element per item.
• lastServicedAt and warrantyExpiresAt are ISO 8601 timestamps in UTC, such as 2026-09-15T00:00:00Z. They come back with milliseconds.
• catalogEntryId: null unlinks the template. sleepingCapacity: null drops the override so the catalog value applies again.
• metadata replaces the whole stored object, and unchanged text isn’t re-translated, as for catalog entries.
• An element in another organization, or on a property outside an OAuth token’s access, returns 404 not_found_error.

Deleting an element

DELETE /property-elements/{id} deletes the element permanently and returns {"success": true}. It also deletes every item nested under it, and the attachments and inventory items recorded against each deleted element. Tasks, task checklist rows and scopes that pointed at a deleted element keep existing but lose that link. There is no undo: read the tree with listPropertyElements first if you may need to recreate it.

• While your organization’s system arrival, completion and general categories are live, the last area of each on a property can’t be deleted: the call returns 403. A duplicate of one of those areas can go while another remains. Once a category is retired, its leftover areas can be deleted.
• If the element moves to another category, property or level while the delete runs, the call returns 409. Read it again and retry.

Sleeping capacity

A property’s sleeping total is derived from its elements: each element counts its own sleepingCapacity, or its catalog entry’s when its own is null, or 0. Only elements whose category has the Sleeping capacity field count, and elements the property’s group shares count too. It doesn’t change the property’s maxGuests.

Attachments

An element or a catalog entry can hold files for staff: manuals, warranties, receipts and photos. A file on a catalog entry shows on every element linked to it. Attachments are private staff documents. They aren’t shown to guests; for a guest-facing house manual use createPortalManual.

Listing attachments

GET /element-attachments returns an unpaginated array, sorted by attachmentType and then oldest first. It returns each file’s name, type and size, not its contents or a download link.

curl "https://api-us.suiteop.com/api/v1/element-attachments?instanceId=7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d" \
  -H "Authorization: Bearer sk_live_your_key_here"

{
  "data": [
    {
      "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
      "fileName": "Dishwasher warranty.pdf",
      "fileType": "application/pdf",
      "size": 284113,
      "attachmentType": "warranty",
      "catalogEntryId": null,
      "instanceId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
      "createdAt": "2026-10-12T09:14:02.000Z"
    }
  ],
  "meta": { "requestId": "…" }
}

• instanceId returns the element’s own files plus those of its linked catalog entry. Tell them apart by which of instanceId and catalogEntryId is set.
• catalogEntryId alone returns that entry’s files.
• With neither, you get every catalog entry’s files plus those of the elements on properties you can reach.
• An element you can’t reach, or one that doesn’t exist, returns an empty array rather than 404.

Attaching a file

You can’t upload bytes to this operation. POST /element-attachments copies a file SuiteOp already holds, from one of two sources:

• dropBoxFileId: a ready file from an image drop box, the id that listDropBoxImages returns. A PDF is copied as the PDF, up to 10 MB. An image is copied as its re-encoded JPEG, and its name ends in .jpg.
• fileUrl: one of your organization’s SuiteOp image links, for example an imageUrl another operation returned. It must be a PDF or an image of at most 10 MB.

Send exactly one source, and exactly one owner: instanceId (an element from listPropertyElements) or catalogEntryId (an entry from listElementCatalog). attachmentType is required: manual, warranty, photo, receipt or other.

curl -X POST https://api-us.suiteop.com/api/v1/element-attachments \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Idempotency-Key: 4d5e6f70-8192-4a3b-9c4d-5e6f7a8b9c0d" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceId": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d",
    "attachmentType": "warranty",
    "dropBoxFileId": "9c4d2e7f-3a1b-4c8d-9e6f-1a2b3c4d5e6f",
    "fileName": "Dishwasher warranty.pdf"
  }'

The response is 201 with the attachment, in the same shape as a list row.

• fileName (up to 255 characters) is the name shown on the element. Omit it to keep the source’s name.
• The file is copied into private storage, so the attachment outlives the drop box, which is deleted 30 days after its newest upload.
• 400 validation_error: both or neither owner, both or neither source, a drop box file that is still pending, failed or over 10 MB, or a fileUrl that isn’t one of your SuiteOp links, is over 10 MB, or isn’t a PDF or an image.
• 404 not_found_error: an element, catalog entry or drop box file of another organization, an element on a property you can’t reach, or a fileUrl whose file doesn’t exist.

Deleting an attachment

DELETE /element-attachments/{id} deletes the attachment permanently and returns {"success": true}. The stored file is removed right after. Deleting a catalog entry’s file removes it from every element linked to that entry. There is no undo. An attachment of an element you can’t reach returns 404 not_found_error.

Attachments are also deleted with their owner: see Deleting a catalog entry and Deleting an element.

How elements connect to tasks

Property element ids are what the task operations take when work is about one specific thing:

• createTask accepts elementInstanceId, for example to file a repair against one dishwasher so it lands in that element’s history. It needs a propertyId. Elements shared by the property’s group are accepted too.
• updateTask can re-point elementInstanceId or clear it with null. It is checked against the property the task ends up on, so moving a task to another property while it still points at the old property’s element is rejected. Send null in the same call.
• listTasks filters by elementInstanceId, which gives the repair history of one element. Combine it with statuses to check whether a repair is already open.
• addTaskRequirement (POST /task-requirements) attaches a checklist row to one element of the task’s property with elementInstanceId. Instead, elementCategory (general, arrival or completion) targets that property’s mandatory area and creates it if it is missing.
• Template requirement groups (addTemplateGroup, POST /task-template-groups) target categories, not elements. targetCategoryId, a category id from listElementCategories, makes the group repeat once for every matching element on the task’s property. targetLevel (area or item) and parentCategoryId narrow the match. targetLevel without targetCategoryId is rejected, and so is parentCategoryId with targetLevel: "area". So the elements a property has decide which checklist rows a templated task gets.

Pitfalls

Caution

• Look up category ids every time. They differ per organization. Match on name and level from listElementCategories, and skip archived: true rows for anything new.
• Don’t send quantity. It’s on its way out of the API, and sending it creates that many elements but returns only the first. Create one element per physical item instead.
• Linking a catalog entry doesn’t copy its fields. Send make, model and the rest on the element yourself.
• A parent you can’t see is 404, not 400. Every other wrong level or parent pairing is 400 validation_error.
• An empty list is ambiguous. listPropertyElements returns [] for a property with no elements and for a property you can’t reach.
• Deletes can’t be undone, and nothing can be reordered through the API, so double-check before creating or deleting. Deleting an area deletes the items under it. Use an Idempotency-Key on every POST so a network retry doesn’t create a duplicate element or attachment.
• Catalog names are unique per category. A 409 on create means the entry already exists; find it with listElementCatalog instead of retrying.
• metadata is replaced, not merged, on both update operations.