Directory

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

📘

All write paths require site management permissions.

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"
  }
}
KeyTypeDescription
idStringThe folder ID
nameStringThe name of the folder
org_idStringThe ID of the creator's organisation
creator_idStringThe ID of the creator
created_atStringISO date and time when the folder was created
modified_atStringISO date and time when the folder was last modified
meta_labelStringThe 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
  }
}
KeyTypeDescription
folderObjectThe folder object
member_countNumberThe number of users directly assigned to this folder
has_childrenBooleanWhether or not the folder has any children folders
inherited_member_countNumberThe number of inherited members (members assigned to parent folders)
depthNumberThe depth in the hierarchy starting from 1
children_countNumberThe 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
  }
}
KeyTypeDescription
folderArrayThe folder object
ancestorsArrayAn array of parent folder objects (ordered from closest relation to furthest)
members_countNumberThe 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
}
KeyTypeDescription
folderObjectThe folder object
parent_idStringThe UUID of the parent folder; folders with no parent will use a Nil/Empty UUID
depthNumberThe depth in the hierarchy starting from 1
members_countNumberThe number of users directly assigned to this folder

Folder order by

{
  "sort_order": 1
}
KeyTypeDescription
sort_orderNumberThe 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"
}
KeyTypeDescription
notBoolean(required) Whether to include or exclude the filter. {"not": false} would mean include.
meta_labelString(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"
}
KeyTypeDescription
notBoolean(required) Whether to include or exclude the filter. {"not": false} would mean include.
folder_idString(required) A meta_label to include or exclude from the results; e.g. 4fb56fa8-fa23-4a9c-907e-8367abc75a2d