This endpoint performs an upsert operation: it creates a new folder or updates an existing one
based on the identifier you provide.

Folder Identification

You must provide at most one of the following identifiers (providing both will result in an error):

1. folder_id (integer):

• Use the internal Customerly folder ID to update an existing folder
• If the folder doesn't exist, a 404 error will be returned

2. custom_folder_id (string):

• Use your custom identifier for upsert operations
• If a folder with this custom_folder_id exists, it will be updated
• If it doesn't exist, a new folder will be created with this identifier
• Must be unique within your app

If neither identifier is provided, a new folder will always be created.

Important: You cannot specify both folder_id and custom_folder_id in the same request.

Folder Hierarchy

Folders support a single level of nesting. Use polymorphic_parent_folder_id to
set a parent folder. The parent must be a root folder (cannot itself have a parent).

Wherever a polymorphic_folder_id is accepted (GET/DELETE folder endpoints and document endpoints),
you can pass either the numeric Customerly folder ID (e.g., 10) or your custom folder ID with the
cid: prefix (e.g., cid:fld_manuals).

Content Visibility

Use contact_segment_ids and company_segment_ids to restrict access to this folder and its contents
inside Aura (the AI assistant). Only contacts and companies belonging to the specified segments
will be able to access this content through Aura.

Visibility rules set on a folder are automatically inherited by all documents inside it that do
not have their own explicit visibility rules.

• Omit the field (or pass null) to leave existing visibilities unchanged.
• Pass an empty array [] to remove all visibility restrictions for that segment type.
• Pass a non-empty array to replace the current visibilities with exactly those segment IDs.

Requires the content_visibility feature on your plan.