Update a Folder

Rename and/or move a folder. Rejects cycles.

PATCH /folders/{folder_id}

Patch Folder

cURL

curl --request PATCH \
  --url https://api.example.com/folders/{folder_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "parent_id": "<string>"
}
'

200

{}

Renames and/or moves a folder. Only the fields you send are changed (Pydantic exclude_unset), and parent_id is treated specially: to move a folder back to root, send "parent_id": null explicitly — the endpoint distinguishes that from omitting the field entirely.

Moving a folder rejects cycles: the endpoint fetches every folder in the org and walks the in-memory tree to find every descendant of the folder being moved (org folder counts are assumed small), then rejects the move with 400 if the proposed new parent is one of those descendants or is the folder itself — rather than corrupting the tree.

Folder names are unique per parent, case-insensitively — the same (org_id, parent_id, lower(name)) constraint as Create a Folder — so renaming into a collision returns 409.

Auth

Requires a CRM manage scope and an active organization on the token. Any *:manage scope qualifies — in practice contacts:manage, deals:manage, companies:manage, or activities:manage.

Response

Returns the updated folder row (same shape as List Folders’s folders[]).

Errors

Status	Cause
400 Bad Request	No fields set; name empty after trimming; new parent_id equals folder_id; or new parent_id is a descendant of folder_id (would create a cycle).
404 Not Found	folder_id doesn’t exist in this org.
409 Conflict	The rename/move collides with an existing sibling name. Also returned if parent_id names a folder that doesn’t exist — unlike Create a Folder, this endpoint doesn’t pre-check that the new parent exists, so an invalid parent_id surfaces as the same foreign-key-driven 409 as a name collision. Verify the parent with List Folders first if you’re not sure it exists.

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

folder_id · string · required

UUID of the folder to rename and/or move.

Body

application/json

name · string | null

Renames the folder.

parent_id · string | null

Moves the folder under this parent id; pass null explicitly to move it back to root. Rejected if it would create a cycle.

Response

200

application/json

Successful Response

The response is of type Response Patch Folder Folders Folder Id Patch · object.