Directory

The SafetyCulture API gives you access to list, search, create, update, and delete folders.

Each organization can only have up to 50,000 sites.

Each user can only be a member of up to 20 sites. Inherited memberships are not included.

📘 All write paths require the "site management" permission.

Folder (sites) Format

This section describes the complete folder response format.

Note that meta_label is different from custom labels which are used for display purposes only.
Refer to Get custom labels for more information about retrieving and using custom site labels.

Folder

{
  "folder": {
    "id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2f",
    "name": "221 Sturt st",
    "org_id": "d31e24be-e7a4-4a28-a230-044f850041fc",
    "creator_id": "a3452937-9fa7-4ba2-9ffa-c3bbee3fc947",
    "created_at": "2020-04-28T04:14:31:00Z",
    "modified_at": "2020-04-28T04:14:31:00Z",
    "meta_label": "location"
  }
}

Key	Type	Description
`id`	String	The folder ID
`name`	String	The name of the folder
`org_id`	String	The ID of the creator's organisation
`creator_id`	String	The ID of the creator
`created_at`	String	ISO date and time when the folder was created
`modified_at`	String	ISO date and time when the folder was last modified
`meta_label`	String	The label of the folder

Folder with member count

{
  "folder_with_member_count": {
    "folder": {
      "id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2f",
      "name": "221 Sturt st",
      "org_id": "d31e24be-e7a4-4a28-a230-044f850041fc",
      "creator_id": "a3452937-9fa7-4ba2-9ffa-c3bbee3fc947",
      "created_at": "2020-04-28T04:14:31:00Z",
      "modified_at": "2020-04-28T04:14:31:00Z",
      "meta_label": "location"
    },
    "members_count": 5,
    "has_children": false,
    "inherited_member_count": 10,
    "depth": 3,
    "children_count": 0
  }
}

Key	Type	Description
`folder`	Object	The folder object
`member_count`	Number	The number of users directly assigned to this folder
`has_children`	Boolean	Whether or not the folder has any children folders
`inherited_member_count`	Number	The number of inherited members (members assigned to parent folders)
`depth`	Number	The depth in the hierarchy starting from `1`
`children_count`	Number	The count of children folders underneath this folder

Folder with ancestors

{
  "folder_with_ancestors": {
    "folder": {
      "id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2f",
      "name": "221 Sturt st",
      "org_id": "d31e24be-e7a4-4a28-a230-044f850041fc",
      "creator_id": "a3452937-9fa7-4ba2-9ffa-c3bbee3fc947",
      "created_at": "2020-04-28T04:14:31:00Z",
      "modified_at": "2020-04-28T04:14:31:00Z",
      "meta_label": "location"
    },
    "ancestors": [
      {
        "id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2d",
        "name": "Townsville",
        "org_id": "d31e24be-e7a4-4a28-a230-044f850041fc",
        "creator_id": "a3452937-9fa7-4ba2-9ffa-c3bbee3fc947",
        "created_at": "2020-04-28T04:14:31:00Z",
        "modified_at": "2020-04-28T04:14:31:00Z",
        "meta_label": "area"
      },
      {
        "id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2c",
        "name": "Queensland",
        "org_id": "d31e24be-e7a4-4a28-a230-044f850041fc",
        "creator_id": "a3452937-9fa7-4ba2-9ffa-c3bbee3fc947",
        "created_at": "2020-04-28T04:14:31:00Z",
        "modified_at": "2020-04-28T04:14:31:00Z",
        "meta_label": "region"
      }
    ],
    "members_count": 5
  }
}

Key	Type	Description
`folder`	Array	The folder object
`ancestors`	Array	An array of parent folder objects (ordered from closest relation to furthest)
`members_count`	Number	The number of users directly assigned to this folder

Folder with parent

{
  "folder": {
    "id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2f",
    "name": "221 Sturt st",
    "org_id": "d31e24be-e7a4-4a28-a230-044f850041fc",
    "creator_id": "a3452937-9fa7-4ba2-9ffa-c3bbee3fc947",
    "created_at": "2020-04-28T04:14:31:00Z",
    "modified_at": "2020-04-28T04:14:31:00Z",
    "meta_label": "location"
  },
  "parent_id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2d",
  "depth": 3,
  "member_count": 5
}

Key	Type	Description
`folder`	Object	The folder object
`parent_id`	String	The UUID of the parent folder; folders with no parent will use a Nil/Empty UUID
`depth`	Number	The depth in the hierarchy starting from `1`
`members_count`	Number	The number of users directly assigned to this folder

Folder order by

{
  "sort_order": 1
}

Key	Type	Description
`sort_order`	Number	The sort order where `1` is ascending and `2` is descending

Folder filter

Folders can be filtered using an array of meta_label and folder_id filter objects.

If meta-label object(s) and folder-id object(s) are used together, folders will be filtered using an AND operation.
If multiple meta-label objects are used, folder meta-labels will be filtered using an OR operation.
If multiple folder-id objects are used, folder ID's will be filtered using an OR operation.

Examples can be seen here.

meta_label filter object

{
  "not": false,
  "meta_label": "location"
}

Key	Type	Description
`not`	Boolean	(required) Whether to include or exclude the filter. `{"not": false}` would mean include.
`meta_label`	String	(required) A meta_label to include or exclude from the results; e.g. `location`

folder_id filter object

{
  "not": false,
  "folder_id": "4fb56fa8-fa23-4a9c-907e-8367abc75a2d"
}

Key	Type	Description
`not`	Boolean	(required) Whether to include or exclude the filter. `{"not": false}` would mean include.
`folder_id`	String	(required) A meta_label to include or exclude from the results; e.g. `4fb56fa8-fa23-4a9c-907e-8367abc75a2d`