Folder object allows users to manage folders for both Udfs (organizing Udfs under each tab related to AbEntry/Lead, Opportunity, Campaign and Case) and Company Library module (general use documents, notes and hyperlinks).

IMPORTANT: the Folder object is currently using the beta version by default (0.x). Which means, if you send payloads without setting the compatibility, you will use the functionality of FolderObject = 0.x. That version supports only Udf folders, and for that reason, we strongly suggest to always use compatibility with FolderObject = 1.x, which supports both Udf and DocumentLibrary folder types. Saying that, make sure to always include the following section in any payload:

"Compatibility": {
    "FolderObject": "1.0" // supports both Udf and DocumentLibrary folders
}

The solution is pretty similar for both Udf and Company Library folders, which only a few differences in terms of validation/required fields. See below some considerations for the Folder object:

Udf folders are created using the following values in the AppliesTo field:
- AbEntry (applies for all types - Contact, Company and Individual)\
- Company\
- Contact\
- Individual\
- Opportunity\
- Case\
- Campaign\
- Lead\
Company Library folders are created using the "DocumentLibrary" value (alone) in the AppliesTo field.\
The concept of "parent" folder applies in both cases: we can create folders within folders. To do that, simply provide the parent folder you want to create the new folder under in the ParentKey field.\
The concept or "root" folder also applies in both cases: it's the top level folder in which everything is created (it's the "parent" of all folders and entries added to it). There is a very special key that represents "root" folder:

Um9vdEZvbGRlcgkw

This is a fixed value that represents "RootFolder 0" (meaning the Id = 0 of a given folder). You can safely use this fixed value whenever you need to reference the "root" folder.\
We can only delete folders that are completely empty. If you try to delete a folder that is associated with at least one file (in case of the Company Library module) or one Udf (in case of the Udf folder), you will receive an error.

HowTo's

Create Udf Folder - AbEntry

// POST https://api.maximizer.com/octopus/Create
// Authorization: Bearer <token>
{
    "Folder": {
        "Data": {
            "Key": null,
            "AppliesTo": [
                "AbEntry"
            ],
            "Name": "My AbEntry Udf Folder"
        }
    },
    "Compatibility": {
        "FolderObject": "1.0" // supports both Udf and DocumentLibrary folders
    }
}

Create Udf Folder - Lead

// POST https://api.maximizer.com/octopus/Create
// Authorization: Bearer <token>
{
    "Folder": {
        "Data": {
            "Key": null,
            "AppliesTo": [
                "Lead"
            ],
            "Name": "My Lead Udf Folder"
        }
    },
    "Compatibility": {
        "FolderObject": "1.0" // supports both Udf and DocumentLibrary folders
    }
}

Create Udf Folder - Opportunity

// POST https://api.maximizer.com/octopus/Create
// Authorization: Bearer <token>
{
    "Folder": {
        "Data": {
            "Key": null,
            "AppliesTo": [
                "Opportunity"
            ],
            "Name": "My Opportunity Udf Folder"
        }
    },
    "Compatibility": {
        "FolderObject": "1.0" // supports both Udf and DocumentLibrary folders
    }
}

Create Udf Folder - Campaign

// POST https://api.maximizer.com/octopus/Create
// Authorization: Bearer <token>
{
    "Folder": {
        "Data": {
            "Key": null,
            "AppliesTo": [
                "Campaign"
            ],
            "Name": "My Campaign Udf Folder"
        }
    },
    "Compatibility": {
        "FolderObject": "1.0" // supports both Udf and DocumentLibrary folders
    }
}

Create Udf Folder - Case

// POST https://api.maximizer.com/octopus/Create
// Authorization: Bearer <token>
{
    "Folder": {
        "Data": {
            "Key": null,
            "AppliesTo": [
                "Case"
            ],
            "Name": "My Case Udf Folder"
        }
    },
    "Compatibility": {
        "FolderObject": "1.0" // supports both Udf and DocumentLibrary folders
    }
}

Metadata

Read Folder metadata (simple)

// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
    "Schema": {
        "Scope": {
            "Fields": 1
        },
        "Criteria": {
            "SearchQuery": {
                "Key": {
                    "$TREE": "/Folder"
                }
            }
        }
    },
    "Compatibility": {
        "SchemaObject": "1.0"
    }
}

Read Folder metadata (more)

// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
    "Schema": {
        "Scope": {
            "Fields": {
                "Key": 1,
                "Alias": 1,
                "Type": 1,
                "Name": 1,
                "AppliesTo": 1,
                "Sortable": 1,
                "Queryable": 1,
                "Assignable": 1,
                "Mandatory": 1,
                "Attributes": 1,
                "HasOption": 1,
                "DisplayValue": 1
            }
        },
        "Criteria": {
            "SearchQuery": {
                "Key": {
                    "$TREE": "/Folder"
                }
            }
        }
    },
    "Compatibility": {
        "SchemaObject": "1.0"
    }
}

FieldOptions

Read Folder FieldOptions - AppliesTo

// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
    "Folder": {
        "FieldOptions": {
            "AppliesTo": {
                "Key": 1,
                "DisplayValue": 1
            }
        }
    }
}

Folder CRUD

Create - Folder

// POST https://api.maximizer.com/octopus/Create
// Authorization: Bearer <token>
{
    "Folder": {
        "Data": {
            "Key": null,
            // Folders can be one of two types:
            // - Udf folder => used to organize Udfs created under a specific entity (AbEntry, Opportunity, Case, etc)
            // - DocumentLibrary folder => used to organize documents on the DocumentLibrary module (general use documents, not tied to any object)
            // When creating a folder for DocumentLibrary, that's the only value that should be specified in the AppliesTo field.
            // When creating a Udf folder, you should specify the entity type under which the new Udf folder will be created.
            "AppliesTo": [
                "DocumentLibrary"
            ], // Mandatory
            "Name": "My Test Folder", // Mandatory
            // The parent folder must exist to be used here. This is an optional field and the folder will be created in the root of the folder tree if no parent folder is provided. If you every need to reference the "root" folder, the key value will ALWAYS be this: Um9vdEZvbGRlcgkw
            "ParentFolderKey": "Um9vdEZvbGRlcgkw", // Mandatory
            "Inactive": false
        }
    },
    "Compatibility": {
        "FolderObject": "1.0" // supports both Udf and DocumentLibrary folders
    }
}

Read - Folder

// POST https://api.maximizer.com/octopus/Read
// Authorization: Bearer <token>
{
    "Folder": {
        "Scope": {
            "Fields": {
                "Key": 1,
                "AppliesTo": 1,
                "Name": 1,
                "Path": 1,
                "ParentFolderKey": 1,
                "Creator": 1,
                "CreationDate": 1,
                "Inactive": 1
            }
        },
        "Criteria": {
            "SearchQuery": {},
            "Top": 3
        }
    },
    "Compatibility": {
        "FolderObject": "1.0" // supports both Udf and DocumentLibrary folders
    }
}

Update - Folder

// POST https://api.maximizer.com/octopus/Update
// Authorization: Bearer <token>
{
    "Folder": {
        "Data": {
            "Key": "RG9jRm9sZGVyCTMwNDk3MjA0OA==", // Mandatory
            "Name": "My Test Folder Updated",
            // In case you want to change the parent folder, provide the ParentFolderKey where you want the folder "moved" to (folder MUST exist). If you want to move the folder to the root of folder, use this fixed value: Um9vdEZvbGRlcgkw
            "ParentFolderKey": "Um9vdEZvbGRlcgkw",
            "Inactive": true
        }
    },
    "Compatibility": {
        "FolderObject": "1.0" // supports both Udf and DocumentLibrary folders
    }
}

Delete - Folder

// POST https://api.maximizer.com/octopus/Delete
// Authorization: Bearer <token>
{
    "Folder": {
        "Data": {
            // Constraint: to delete a folder, it MUST be empty. Trying to delete a folder that is not empty will result in an error.
            "Key": "RG9jRm9sZGVyCTMwNDk3MjA0OA==" // Mandatory
        }
    },
    "Compatibility": {
        "FolderObject": "1.0" // supports both Udf and DocumentLibrary folders
    }
}