SubOrgs

a suborg (sub organization) is a subdivision of your primevault organization that groups the users and resources belonging to a customer or business unit it lets you manage access to each group separately while keeping everything under one parent organization create and list sub organizations within the authenticated api user's organization the external api currently exposes collection creation and listing only the sdk examples assume an authenticated apiclient , named apiclient in javascript or api client in python access and permissions requests must use an active api user with the admin or owner role the organization and acting user are derived from authentication; caller supplied organization or user identifiers cannot change the scope create a suborg post /api/external/sub orgs/ create a managed end user suborg in the authenticated organization creation requires organization wide access as described above request body field type required description name string yes non empty suborg name the name must be unique within the organization { "name" "primevault customer" } response — 201 created the response is a suborg object ids and timestamps below are illustrative { "id" "a648fa0d 4ca9 4f4f a520 7ef5e9db34eb", "orgid" "a30d5e99 7076 45da a933 0d5642619340", "name" "primevault customer", "controlmode" "managed", "createdat" "2026 09 14t12 00 00z", "updatedat" "2026 09 14t12 00 00z", "isdeleted" false, "version" 1 } javascript sdk const suborg = await apiclient createsuborg({ name "primevault customer", }); console log(suborg id, suborg controlmode); python sdk from primevault python sdk types import createsuborgrequest sub org = api client create sub org( createsuborgrequest(name="primevault customer") ) print(sub org id, sub org controlmode) list suborgs get /api/external/sub orgs/ returns the suborgs visible to the authenticated api user results are scoped to the organization, exclude deleted rows, and are ordered newest first by creation time, with id as the tie breaker query parameters parameter type required description name string no case insensitive sql pattern match use %primevault% to match names containing primevault, or primevault% for a prefix % matches any sequence and matches one character limit integer no page size default 20; effective range 1–100 cursor string no opaque cursor returned as nextcursor omit it or send an empty value for the first page url encoded request example get /api/external/sub orgs/?limit=20\&name=%25primevault%25 response — 200 ok { "results" \[ { "id" "a648fa0d 4ca9 4f4f a520 7ef5e9db34eb", "orgid" "a30d5e99 7076 45da a933 0d5642619340", "name" "primevault customer", "controlmode" "managed", "createdat" "2026 09 14t12 00 00z", "updatedat" "2026 09 14t12 00 00z", "isdeleted" false, "version" 1 } ], "nextcursor" null, "hasnext" false } when hasnext is true, pass nextcursor unchanged into the next request keep the same name filter and page size while paging an empty result is results \[] , nextcursor null , and hasnext false this response does not include a total count javascript sdk — read every page import type { suborg } from "@primevault/js api sdk"; const suborgs suborg\[] = \[]; let cursor string | null = null; do { const page = await apiclient getsuborgs( { name "%primevault%" }, 20, cursor, ); suborgs push( page results); cursor = page nextcursor; } while (cursor); python sdk — read every page from typing import list, optional from primevault python sdk types import suborg sub orgs list\[suborg] = \[] cursor optional\[str] = none while true page = api client get sub orgs( {"name" "%primevault%"}, limit=20, cursor=cursor ) sub orgs extend(page results) if not page hasnext break cursor = page nextcursor data models both sdks provide createsuborgrequest , suborg , suborglistresponse , and suborgcontrolmode createsuborgrequest contains one required field name string it has no controlmode field suborg field type description id string (uuid) suborg identifier orgid string (uuid) owning organization name string suborg name controlmode suborgcontrolmode | null read only metadata new suborgs created here return managed createdat string (date time) creation timestamp updatedat string (date time) last update timestamp isdeleted boolean deletion flag listed rows are not deleted the response does not expose type , status , or parentsuborgid python response attributes keep the same camelcase field names as the json response suborglistresponse field type description results suborg\[] suborgs on the current page nextcursor string | null cursor for the next page, or null at the end hasnext boolean whether another page is available suborgcontrolmode the response enum contains managed and independent ; existing data can also return null these are response values, not creation options this api always creates with managed and rejects caller supplied control mode sdk method reference operation javascript python returns create createsuborg create sub org suborg list getsuborgs get sub orgs suborglistresponse both list methods accept optional name filters in params , a limit that defaults to 20, and a cursor javascript methods return promises python methods return dataclass instances; controlmode is parsed as suborgcontrolmode when non null errors and supported operations status when it occurs 400 bad request missing or invalid name, duplicate name, any supplied controlmode, unsupported main creation, or an invalid pagination cursor 401 unauthorized missing or invalid authentication, or an inactive api user 403 forbidden a role other than admin/owner; an unavailable or non active assigned home; or creation without organization wide access only get and post on /api/external/sub orgs/ are available there are no external retrieve by id, update, delete, or embedded user actions in this section's api